version numbers in ELPA

version numbers in ELPA

[Yoni Rabkin]

Hello all,

As I'm preparing another release of rt-liberation for ELPA I noticed
that in my code I have:

;; Version: 2.01

...but ELPA displays it, and makes the directories under
~/.emacs.d/elpa, as "2.1".

So when I release 2.02, it will probably turn into 2.2... which might be
confusing if I ever try to release an actual 2.2....

Are there some implicit rules to follow as to how we should number
versions going to ELPA? Are there some explicit rules I just skimmed
over and didn't take note of?

thanks

-- 
   "Cut your own wood and it will warm you twice"

Re: version numbers in ELPA

[Stefan Monnier]

> As I'm preparing another release of rt-liberation for ELPA I noticed
> that in my code I have:
>
> ;; Version: 2.01
>
> ...but ELPA displays it, and makes the directories under
> ~/.emacs.d/elpa, as "2.1".

Yes, version numbers are defined in ELPA (notice: not "GNU ELPA" but
"ELPA") as sequences of numbers.  Since 1 and 01 are one and the same
number, then ... 2.01 is the same as 2.1.

> Are there some implicit rules to follow as to how we should number
> versions going to ELPA? Are there some explicit rules I just skimmed
> over and didn't take note of?

Yes, the version numbers need to obey `version-to-list` and the actual
string used to represent the version number in the name of the tarball
need to be "canonicalized" by passing them to `version-to-list` and then
recreating a corresponding string out of it with `package-version-join`
(defined in `package.el`).  This need is because the `archive-contents`
file (which lists the tarballs available in a given ELPA server) give
the versions in the form of a list of numbers rather than a string, and
then `package.el` needs to "guess" the name of the corresponding tarball
by creating a string out of it.


        Stefan

Re: version numbers in ELPA

[Yoni Rabkin]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> As I'm preparing another release of rt-liberation for ELPA I noticed
>> that in my code I have:
>>
>> ;; Version: 2.01
>>
>> ...but ELPA displays it, and makes the directories under
>> ~/.emacs.d/elpa, as "2.1".
>
> Yes, version numbers are defined in ELPA (notice: not "GNU ELPA" but
> "ELPA") as sequences of numbers.  Since 1 and 01 are one and the same
> number, then ... 2.01 is the same as 2.1.
>
>> Are there some implicit rules to follow as to how we should number
>> versions going to ELPA? Are there some explicit rules I just skimmed
>> over and didn't take note of?
>
> Yes, the version numbers need to obey `version-to-list` and the actual
> string used to represent the version number in the name of the tarball
> need to be "canonicalized" by passing them to `version-to-list` and then
> recreating a corresponding string out of it with `package-version-join`
> (defined in `package.el`).  This need is because the `archive-contents`
> file (which lists the tarballs available in a given ELPA server) give
> the versions in the form of a list of numbers rather than a string, and
> then `package.el` needs to "guess" the name of the corresponding tarball
> by creating a string out of it.

Understood; thank you.

I'll change the version numbering accordingly.

-- 
   "Cut your own wood and it will warm you twice"

Re: version numbers in ELPA

[Michael Albinus]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> Yes, version numbers are defined in ELPA (notice: not "GNU ELPA" but
> "ELPA") as sequences of numbers.  Since 1 and 01 are one and the same
> number, then ... 2.01 is the same as 2.1.
>
>> Are there some implicit rules to follow as to how we should number
>> versions going to ELPA? Are there some explicit rules I just skimmed
>> over and didn't take note of?
>
> Yes, the version numbers need to obey `version-to-list` and the actual
> string used to represent the version number in the name of the tarball
> need to be "canonicalized" by passing them to `version-to-list` and then
> recreating a corresponding string out of it with `package-version-join`
> (defined in `package.el`).  This need is because the `archive-contents`
> file (which lists the tarballs available in a given ELPA server) give
> the versions in the form of a list of numbers rather than a string, and
> then `package.el` needs to "guess" the name of the corresponding tarball
> by creating a string out of it.

Perhaps we can recommend semantic versioning <https://semver.org/>? This
speaks also about the syntax, leading zeroes are forbidden ("MUST NOT").

`version-to-list' seems to be close to this, but I haven't checked for
differences.

>         Stefan

Best regards, Michael.

Re: version numbers in ELPA

[chad]

[-- Attachment #1: Type: text/plain, Size: 636 bytes --]

On Wed, Feb 17, 2021 at 9:12 AM Yoni Rabkin <yoni@rabkins.net> wrote:

>
> So when I release 2.02, it will probably turn into 2.2... which might be
> confusing if I ever try to release an actual 2.2....


 This text implies that you were at least thinking about releasing a
version 2.2 and expecting users to think that it was something different
from version 2.02. Is that true, or were you maybe just surprised that the
leading zero was dropped? If the latter, you're in pretty good company, and
the help for version-to-list and version-regexp-alist will be helpful. If
the former... please don't do that? :-)

Hope that helps,
~Chad

[-- Attachment #2: Type: text/html, Size: 1005 bytes --]

Re: version numbers in ELPA

[Yoni Rabkin]

chad <yandros@gmail.com> writes:

> On Wed, Feb 17, 2021 at 9:12 AM Yoni Rabkin <yoni@rabkins.net> wrote:
>
>>
>> So when I release 2.02, it will probably turn into 2.2... which might be
>> confusing if I ever try to release an actual 2.2....
>
>
>  This text implies that you were at least thinking about releasing a
> version 2.2 and expecting users to think that it was something different
> from version 2.02. Is that true, or were you maybe just surprised that the
> leading zero was dropped? If the latter, you're in pretty good company, and
> the help for version-to-list and version-regexp-alist will be helpful. If
> the former... please don't do that? :-)

<please read without taking too seriously>
I was indeed surprised that the zero was dropped; in my head 2.02 is a
different number than 2.2. In fact, Emacs itself tells me that the
difference between 2.2 and 2.02 is exactly... um 0.18000000000000016...
</please read without taking too seriously>

I am in no way complaining or asking for changing anything. Just wanted
clarification. I've already gone ahead and changed the way I version
rt-liberation to simply "X.Y".

-- 
   "Cut your own wood and it will warm you twice"