Eli Zaretskii writes: >> From: Philip Kaludercic >> Cc: Eli Zaretskii , 60418@debbugs.gnu.org, >> felician.nemeth@gmail.com, stefankangas@gmail.com >> Date: Fri, 05 May 2023 05:04:59 +0000 >> >> Tony Zorman writes: >> >> > You're right, but I don't think I'm using them as synonyms. There is a >> > big difference between >> > >> > (package-vc-install "foo") >> > >> > which installs the latest "commit" (or revision, which I'm actually >> > using as a synonym to commit) of a package, and >> > >> > (package-vc-install "foo" :last-release) >> > >> > which installs the latest "release". A release, as defined by >> > package-vc.el seems to be 'the latest revision that bumps the "Version" >> > tag.' It is queried in the package-vc--release-rev function, and >> > actually retrieved in vc-retrieve-tag. The "Version" tag is, I think, >> > just the "Version: XXX" string that's specified in the top comment of >> > the main elisp file of the respective repository. >> >> How about we just say "the commit of the latest release"? > > When package-vc-install is used, what is "the latest release"? isn't > that the HEAD of the default branch? IOW, what about packages that > make no releases at all? No, the commit of the latest release is interpreted the same way as elpa-admin.el does, namely the last revision that modified the "Version" header. If no such commit can be found, then a message is printed out and the installation continues under the assumption that the package is using a rolling-release model. >> >> All I know is that when I've read the documentation you wrote, I asked >> >> myself "what is meant by 'release' here?" I found the answer when you >> >> later wrote "last commit". >> >> >> >> Are you talking about commits? More generally, what kind of "release >> >> IDs" does :rev accept as its valid value? >> > >> > The :rev keyword accepts the same as REV of package-vc-install, which is >> > either >> > >> > - nil, signaling that the latest commit should be installed, >> > >> > - :last-release, signaling that the last release should be installed, >> > or >> > >> > - a "version string" appropriate for the respective version control >> > system, specifying that version (e.g., a specific commit hash). >> >> All correct. >> >> >> I understand that the same confusion could exist elsewhere, but that >> >> doesn't mean we should proliferate it or even live with what we have. >> >> We should instead clarify this in every place where we use this >> >> terminology. >> >> >> >> So let's figure out what are these "releases", and then let's examine >> >> the existing and the new documentation and see if we need to get our >> >> terminology right there. >> > >> > I totally agree, and I think the fact that "release" means "when has the >> > release version as specified in the main .el file changed" should be >> > documented somewhere (if it is I didn't see it). Sorry that this has >> > caused so much confusion. >> >> Are there any other places where we can fix this confusion? > > I guess the documentation of package-vc-install shares these issues? How does this sound like to you: