FAQ
http://search.cpan.org/~dagolden/CPAN-Meta-2.101091/lib/CPAN/Meta/Spec.pm#Comparing_Version_Numbers
is an insufficient description about how to compare version numbers. The spec
should not depend on any implementation, in this case version.pm.

A description of the algorithm of how to compare version numbers is necessary
for a complete spec. There would be four sections:

1) Comparing decimal to decimal
2) Comparing dotted to dotted
3) Comparing dotted to decimal
4) Notes about alpha versions


Decimal to Decimal
------------------
DEFINITION: Decimal versions are compared as normal decimal numbers.

EXAMPLE:
1.0 = 1.0
1.0 = 1.00
1.0 = 1
2.0 > 1.0
1.9 > 1.10

RECOMMENDATION: To avoid confusion, users are encouraged to use a fixed number
of decimal places in their versions such that comparing as numbers and
comparing as dotted pairs works the same. For example, if your first release
is 1.00 then your second should be 1.01.


Dotted to Dotted
----------------
DEFINITION: Each integer is compared as an integer with its counterpart in
sequence. If any are not equal, the comparison stops. Otherwise if all are
equal the two versions are equal. Any missing integers are treated as 0.

EXAMPLE:
v1.0.0 = v1.0.0
v1.0 = v1.0.0
v1 = v1.0.0
v1 < v1.1
v1.02 > v1.1
v2.1 > v1.9.9

NOTE: This appears to jive with version.pm

RECOMMENDATION: We recommend using at least 3 integers to avoid confusion
with decimal versions.


Dotted to Decimal
-----------------
RECOMMENDATION: To avoid confusion, when changing between dotted and decimal
versions, it is recommend you increment the first integer. 1.09 should be
followed by 2.0.0.

DEFINITION:
When comparing dotted version numbers with decimal version numbers, the
decimal is first converted to a dotted version. Then they are compared as
dotted versions.

1) The decimal part is multiplied by 1000.
2) The result is treated as the next integer.
2a) If the result is a decimal, goto 1.
3) Alpha versions are left alone.

EXAMPLE:
1.02 -> v1.20.0
1.2 -> v1.200.0
1.2001 -> v1.200.100
1.02_01 -> v1.20.0_01

NOTE: This appears to jive with version.pm


Notes about alpha versions
--------------------------
DEFINITION:
1) Strip off the alpha version
2) If they are equal, the alpha version is the lesser.
2b) If they are both alphas, compare the alpha numbers as integers
3) If they are not, compare normally.

EXAMPLE:
1.00_01 < 1.00
v1.0.0_01 < v1
1.00_00 < 1.00
1.01_01 > 1.00
1.00_01 = 1.00_01
1.00_02 > 1.00_01

RECOMMENDATION: To avoid confusion, increment your version number between an
alpha release and stable. That is, 1.2.3_1 should be followed by 1.2.4.

NOTE: This doesn't appear to jive with version.pm. Here's what it does:
1.0100 < 1.0101_01
1.0101 > 1.0101_00
1.0101 < 1.0101_01

IMO X.Y_Z should always be < than X.Y. That is, 1.01 > 1.01_05. This reads
1.01_05 as "the 5th alpha release of 1.01" just like Firefox 3.6.4 beta 1 will
eventually be followed by Firefox 3.6.4.


--
40. I do not have super-powers.
-- The 213 Things Skippy Is No Longer Allowed To Do In The U.S. Army
http://skippyslist.com/list/

Search Discussions

  • David Golden at Apr 19, 2010 at 1:02 pm
    Michael -- I appreciate the suggestion, but the spec is done. I did
    ask for comments on the final draft a week ago.

    I'm open to considering it for Version 3 at some future time. But
    while I understand the desire not to rely on specific implementations
    like version.pm, that implementation is the same as what Perl itself
    does. We could say "the semantics of Perl 5.12.0" for version
    comparison, but for all practical purposes the toolchain is stuck with
    verison.pm as the external tool we can use for compatibility.

    I truly wish it were different. I wish version objects had never been
    added to Perl. But that train has left the station and we all have to
    make the best of it.

    -- David
    On Mon, Apr 19, 2010 at 8:38 AM, Michael G Schwern wrote:
    http://search.cpan.org/~dagolden/CPAN-Meta-2.101091/lib/CPAN/Meta/Spec.pm#Comparing_Version_Numbers
    is an insufficient description about how to compare version numbers.  The
    spec should not depend on any implementation, in this case version.pm.

    A description of the algorithm of how to compare version numbers is
    necessary for a complete spec.  There would be four sections:

    1) Comparing decimal to decimal
    2) Comparing dotted to dotted
    3) Comparing dotted to decimal
    4) Notes about alpha versions


    Decimal to Decimal
    ------------------
    DEFINITION: Decimal versions are compared as normal decimal numbers.

    EXAMPLE:
    1.0 = 1.0
    1.0 = 1.00
    1.0 = 1
    2.0 > 1.0
    1.9 > 1.10

    RECOMMENDATION: To avoid confusion, users are encouraged to use a fixed
    number of decimal places in their versions such that comparing as numbers
    and comparing as dotted pairs works the same.  For example, if your first
    release is 1.00 then your second should be 1.01.


    Dotted to Dotted
    ----------------
    DEFINITION: Each integer is compared as an integer with its counterpart in
    sequence.  If any are not equal, the comparison stops.  Otherwise if all are
    equal the two versions are equal.  Any missing integers are treated as 0.

    EXAMPLE:
    v1.0.0 = v1.0.0
    v1.0   = v1.0.0
    v1     = v1.0.0
    v1     <  v1.1
    v1.02  >  v1.1
    v2.1   >  v1.9.9

    NOTE: This appears to jive with version.pm

    RECOMMENDATION:  We recommend using at least 3 integers to avoid confusion
    with decimal versions.


    Dotted to Decimal
    -----------------
    RECOMMENDATION:  To avoid confusion, when changing between dotted and
    decimal versions, it is recommend you increment the first integer.  1.09
    should be followed by 2.0.0.

    DEFINITION:
    When comparing dotted version numbers with decimal version numbers, the
    decimal is first converted to a dotted version.  Then they are compared as
    dotted versions.

    1) The decimal part is multiplied by 1000.
    2) The result is treated as the next integer.
    2a) If the result is a decimal, goto 1.
    3) Alpha versions are left alone.

    EXAMPLE:
    1.02     -> v1.20.0
    1.2      -> v1.200.0
    1.2001   -> v1.200.100
    1.02_01  -> v1.20.0_01

    NOTE: This appears to jive with version.pm


    Notes about alpha versions
    --------------------------
    DEFINITION:
    1) Strip off the alpha version
    2) If they are equal, the alpha version is the lesser.
    2b) If they are both alphas, compare the alpha numbers as integers
    3) If they are not, compare normally.

    EXAMPLE:
    1.00_01   < 1.00
    v1.0.0_01 < v1
    1.00_00   < 1.00
    1.01_01   > 1.00
    1.00_01   = 1.00_01
    1.00_02   > 1.00_01

    RECOMMENDATION: To avoid confusion, increment your version number between an
    alpha release and stable.  That is, 1.2.3_1 should be followed by 1.2.4.

    NOTE:  This doesn't appear to jive with version.pm.  Here's what it does:
    1.0100 < 1.0101_01
    1.0101 > 1.0101_00
    1.0101 < 1.0101_01

    IMO X.Y_Z should always be < than X.Y.  That is, 1.01 > 1.01_05.  This reads
    1.01_05 as "the 5th alpha release of 1.01" just like Firefox 3.6.4 beta 1
    will eventually be followed by Firefox 3.6.4.


    --
    40. I do not have super-powers.
    -- The 213 Things Skippy Is No Longer Allowed To Do In The U.S. Army
    http://skippyslist.com/list/
  • Adam Kennedy at Apr 19, 2010 at 1:16 pm
    Or 2.1 once we really understand the implications of things that
    people voted for but which turn out to be a disaster when we try to
    implement them...

    Adam K
    On Mon, Apr 19, 2010 at 11:01 PM, David Golden wrote:
    Michael -- I appreciate the suggestion, but the spec is done.  I did
    ask for comments on the final draft a week ago.

    I'm open to considering it for Version 3 at some future time.  But
    while I understand the desire not to rely on specific implementations
    like version.pm, that implementation is the same as what Perl itself
    does.  We could say "the semantics of Perl 5.12.0" for version
    comparison, but for all practical purposes the toolchain is stuck with
    verison.pm as the external tool we can use for compatibility.

    I truly wish it were different.  I wish version objects had never been
    added to Perl.  But that train has left the station and we all have to
    make the best of it.

    -- David
    On Mon, Apr 19, 2010 at 8:38 AM, Michael G Schwern wrote:
    http://search.cpan.org/~dagolden/CPAN-Meta-2.101091/lib/CPAN/Meta/Spec.pm#Comparing_Version_Numbers
    is an insufficient description about how to compare version numbers.  The
    spec should not depend on any implementation, in this case version.pm.

    A description of the algorithm of how to compare version numbers is
    necessary for a complete spec.  There would be four sections:

    1) Comparing decimal to decimal
    2) Comparing dotted to dotted
    3) Comparing dotted to decimal
    4) Notes about alpha versions


    Decimal to Decimal
    ------------------
    DEFINITION: Decimal versions are compared as normal decimal numbers.

    EXAMPLE:
    1.0 = 1.0
    1.0 = 1.00
    1.0 = 1
    2.0 > 1.0
    1.9 > 1.10

    RECOMMENDATION: To avoid confusion, users are encouraged to use a fixed
    number of decimal places in their versions such that comparing as numbers
    and comparing as dotted pairs works the same.  For example, if your first
    release is 1.00 then your second should be 1.01.


    Dotted to Dotted
    ----------------
    DEFINITION: Each integer is compared as an integer with its counterpart in
    sequence.  If any are not equal, the comparison stops.  Otherwise if all are
    equal the two versions are equal.  Any missing integers are treated as 0.

    EXAMPLE:
    v1.0.0 = v1.0.0
    v1.0   = v1.0.0
    v1     = v1.0.0
    v1     <  v1.1
    v1.02  >  v1.1
    v2.1   >  v1.9.9

    NOTE: This appears to jive with version.pm

    RECOMMENDATION:  We recommend using at least 3 integers to avoid confusion
    with decimal versions.


    Dotted to Decimal
    -----------------
    RECOMMENDATION:  To avoid confusion, when changing between dotted and
    decimal versions, it is recommend you increment the first integer.  1.09
    should be followed by 2.0.0.

    DEFINITION:
    When comparing dotted version numbers with decimal version numbers, the
    decimal is first converted to a dotted version.  Then they are compared as
    dotted versions.

    1) The decimal part is multiplied by 1000.
    2) The result is treated as the next integer.
    2a) If the result is a decimal, goto 1.
    3) Alpha versions are left alone.

    EXAMPLE:
    1.02     -> v1.20.0
    1.2      -> v1.200.0
    1.2001   -> v1.200.100
    1.02_01  -> v1.20.0_01

    NOTE: This appears to jive with version.pm


    Notes about alpha versions
    --------------------------
    DEFINITION:
    1) Strip off the alpha version
    2) If they are equal, the alpha version is the lesser.
    2b) If they are both alphas, compare the alpha numbers as integers
    3) If they are not, compare normally.

    EXAMPLE:
    1.00_01   < 1.00
    v1.0.0_01 < v1
    1.00_00   < 1.00
    1.01_01   > 1.00
    1.00_01   = 1.00_01
    1.00_02   > 1.00_01

    RECOMMENDATION: To avoid confusion, increment your version number between an
    alpha release and stable.  That is, 1.2.3_1 should be followed by 1.2.4.

    NOTE:  This doesn't appear to jive with version.pm.  Here's what it does:
    1.0100 < 1.0101_01
    1.0101 > 1.0101_00
    1.0101 < 1.0101_01

    IMO X.Y_Z should always be < than X.Y.  That is, 1.01 > 1.01_05.  This reads
    1.01_05 as "the 5th alpha release of 1.01" just like Firefox 3.6.4 beta 1
    will eventually be followed by Firefox 3.6.4.


    --
    40. I do not have super-powers.
    -- The 213 Things Skippy Is No Longer Allowed To Do In The U.S. Army
    http://skippyslist.com/list/
  • David Golden at Apr 19, 2010 at 1:51 pm
    Versions going forward will be integers so we can use the fractional part
    for library release versioning.

    But your point taken, Cassandra. :-)

    David

    On Apr 19, 2010 9:16 AM, "Adam Kennedy" wrote:

    Or 2.1 once we really understand the implications of things that
    people voted for but which turn out to be a disaster when we try to
    implement them...

    Adam K

    On Mon, Apr 19, 2010 at 11:01 PM, David Golden wrote: >
    Michael -- I appreciate ...
  • Michael G Schwern at Apr 19, 2010 at 2:23 pm

    David Golden wrote:
    Versions going forward will be integers so we can use the fractional
    part for library release versioning.
    I know, we could use one of those fancy dotted version numbers everyone's been
    talking about!

    (What does the 101091 part of 2.101091 mean anyway?)

    For important things like specifications I've come round to the Semantic
    Versioning way of doing it. http://semver.org/ X increments on an
    incompatible change, Y on a new feature, Z on everything else. This allows
    one to make minor changes and clarifications to the spec look different from
    incompatible OMGYOUDBETTERUPGRADE changes. It frees you to make minor
    releases without causing everyone downstream to have to grovel through the
    change log to see if there was something significant.

    Yeah, I know, irony me advocating X.Y.Z versions, but as long as we're stuck
    with them let's use them.

    In that sense, adding a proper version spec would bring the spec up to v2.0.1
    or v2.1.0, either is arguable. CPAN::Meta can then tack on as many extra dots
    as it wants. v2.1.0.1 would be the second release of CPAN::Meta representing
    v2.1.0 of the spec.


    --
    But there's no sense crying over every mistake.
    You just keep on trying till you run out of cake.
    -- Jonathan Coulton, "Still Alive"
  • Zefram at Apr 19, 2010 at 2:29 pm

    Michael G Schwern wrote:
    (What does the 101091 part of 2.101091 mean anyway?)
    Looks like it's embedding "10-109", an abbreviated ISO 8601 format for
    2010-109, aka 2010-04-19. (Today is the 109th day of the year; specifying
    the date in this manner is known in ISO 8601 as an "ordinal date".)
    Final "1" is a sequence number within the day?

    -zefram
  • Curtis Jewell at Apr 19, 2010 at 2:46 pm

    On Mon, 19 Apr 2010 15:28 +0100, "Zefram" wrote:
    Michael G Schwern wrote:
    (What does the 101091 part of 2.101091 mean anyway?)
    Looks like it's embedding "10-109", an abbreviated ISO 8601 format for
    2010-109, aka 2010-04-19. (Today is the 109th day of the year;
    specifying
    the date in this manner is known in ISO 8601 as an "ordinal date".)
    Final "1" is a sequence number within the day?
    Yes. (Dist::Zilla is quickly making this style of version numbering not
    uncommon.)

    --Curtis
    --
    Curtis Jewell
    csjewell@cpan.org http://csjewell.dreamwidth.org/
    perl@csjewell.fastmail.us http://csjewell.comyr.org/perl/

    "Your random numbers are not that random" -- perl-5.10.1.tar.gz/util.c

    Strawberry Perl for Windows betas: http://strawberryperl.com/beta/
  • Michael G Schwern at Apr 19, 2010 at 3:12 pm

    Zefram wrote:
    Michael G Schwern wrote:
    (What does the 101091 part of 2.101091 mean anyway?)
    Looks like it's embedding "10-109", an abbreviated ISO 8601 format for
    2010-109, aka 2010-04-19. (Today is the 109th day of the year; specifying
    the date in this manner is known in ISO 8601 as an "ordinal date".)
    Final "1" is a sequence number within the day?
    Ahh. Ironic. I was thinking v2.1.20100419 might make sense (major release
    #2, minor release #1, on 2010.04.19), but its disallowed. v2.1.10.04.19
    remains possible (y3k bug, woo!)


    --
    I have a date with some giant cartoon robots and booze.
  • Michael G Schwern at Apr 19, 2010 at 1:43 pm

    David Golden wrote:
    Michael -- I appreciate the suggestion, but the spec is done. I did
    ask for comments on the final draft a week ago.

    I'm open to considering it for Version 3 at some future time. But
    while I understand the desire not to rely on specific implementations
    like version.pm, that implementation is the same as what Perl itself
    does. We could say "the semantics of Perl 5.12.0" for version
    comparison, but for all practical purposes the toolchain is stuck with
    verison.pm as the external tool we can use for compatibility.

    I truly wish it were different. I wish version objects had never been
    added to Perl. But that train has left the station and we all have to
    make the best of it.
    That seems unnecessarily inflexible. We can't do a v2.1?

    To be clear, this doesn't change the spec, it clarifies it. With the
    exception of the bit about the behavior of nearly equivalent alpha versions,
    which is a bit muddy even in version.pm, it does exactly what version.pm does.
    It removes the dependency on version.pm and future discussion of how
    versions should behave become not "whatever version.pm does" but "version.pm
    does what the spec says" which is how it should be.


    --
    The past has a vote, but not a veto.
    -- Mordecai M. Kaplan
  • Jarkko Hietaniemi at Apr 20, 2010 at 12:27 am

    On Monday-201004-19 9:01, David Golden wrote:
    Michael -- I appreciate the suggestion, but the spec is done. I did
    ask for comments on the final draft a week ago.
    Eh? Is the reason for having a spec to adhere to a spec writing spec?
  • Curtis Jewell at Apr 19, 2010 at 2:05 pm

    On Mon, 19 Apr 2010 15:38 +0300, "Michael G Schwern" wrote:
    ...
    Notes about alpha versions
    --------------------------
    DEFINITION:
    1) Strip off the alpha version
    2) If they are equal, the alpha version is the lesser.
    2b) If they are both alphas, compare the alpha numbers as integers
    3) If they are not, compare normally.

    EXAMPLE:
    1.00_01 < 1.00
    v1.0.0_01 < v1
    1.00_00 < 1.00
    1.01_01 > 1.00
    1.00_01 = 1.00_01
    1.00_02 > 1.00_01

    RECOMMENDATION: To avoid confusion, increment your version number between
    an
    alpha release and stable. That is, 1.2.3_1 should be followed by 1.2.4.

    NOTE: This doesn't appear to jive with version.pm. Here's what it does:
    1.0100 < 1.0101_01
    1.0101 > 1.0101_00
    1.0101 < 1.0101_01

    IMO X.Y_Z should always be < than X.Y. That is, 1.01 > 1.01_05. This
    reads
    1.01_05 as "the 5th alpha release of 1.01" just like Firefox 3.6.4 beta 1
    will
    eventually be followed by Firefox 3.6.4.
    I'm sorry, but this section is just *wrong*, IMO. X.Y_Z should always
    be > X.Y. Otherwise, you've just broken (at least the release sequence
    of) previous versions of the toolchain that make the assumption that a
    simple s/_// gets something to compare to that works, without
    version.pm. (Module::Build, for example, went 0.3603 to 0.36_04 to
    0.3605 just within the past few months. I also remember perl doing
    5.005_51 versions in the past during the runup to 5.6.0, as being later
    than 5.00504. )

    The way you're doing it, you have to increment between a release and an
    alpha, as well as between an alpha and a release, or else you ruin
    numerical sequence for stuff that just does the underscore removal.

    You don't get 1.01_05 as "the 5th alpha release of 1.01", if, once
    you're exiting the alpha sequence, you immediately increment to 1.02,
    anyway.

    When X.Y_Z > X.Y, this can be done:
    (ascii art - may not look good with proportional fonts - Just realize
    that 1.103_101 is branched off of 1.103)

    1.102 ---> 1.102001 --> 1.102002 ('maint')
    \
    \---> 1.102_101 ... --> 1.102_103 --> 1.103 ('blead') ---> 1.103001
    ('new maint')
    \
    \---> 1.103_101 ('new blead')

    (this is the way I'm doing Perl::Dist::WiX's numbering. It appears that
    CPAN.pm also is doing something similar to this, only with 2 digit
    segments instead of 3)

    In this case, anything beginning with 1.102 is based off of the 1.102
    "trunk" and it's branches, until the dev version turns into 1.103.

    --Curtis Jewell
    --
    Curtis Jewell
    csjewell@cpan.org http://csjewell.dreamwidth.org/
    perl@csjewell.fastmail.us http://csjewell.comyr.org/perl/

    "Your random numbers are not that random" -- perl-5.10.1.tar.gz/util.c

    Strawberry Perl for Windows betas: http://strawberryperl.com/beta/
  • Michael G Schwern at Apr 19, 2010 at 2:57 pm

    Curtis Jewell wrote:
    IMO X.Y_Z should always be < than X.Y. That is, 1.01 > 1.01_05. This
    reads
    1.01_05 as "the 5th alpha release of 1.01" just like Firefox 3.6.4 beta 1
    will
    eventually be followed by Firefox 3.6.4.
    I'm sorry, but this section is just *wrong*, IMO. X.Y_Z should always
    be > X.Y. Otherwise, you've just broken (at least the release sequence
    of) previous versions of the toolchain that make the assumption that a
    simple s/_// gets something to compare to that works, without
    version.pm. (Module::Build, for example, went 0.3603 to 0.36_04 to
    0.3605 just within the past few months. I also remember perl doing
    5.005_51 versions in the past during the runup to 5.6.0, as being later
    than 5.00504. )
    You're right about that. The traditional way to handle alphas in decimals is
    X.YY_ZZ -> X.YYZZ. My mistake. And it should probably be left that way.
    Which is why we should write this stuff down, perhaps in a spec...

    You don't get 1.01_05 as "the 5th alpha release of 1.01", if, once
    you're exiting the alpha sequence, you immediately increment to 1.02,
    anyway.
    That was a recommendation to avoid any possible ambiguity, so the versions are
    resistant to a reader not entirely groking the details of alpha versions.

    Now, what about vX.YY_ZZ? It appears version.pm is treating it as vX.YY.ZZ,
    except if they'd otherwise be equal the alpha loses.

    v0.36_04 > v0.36.03
    v0.36_04 < v0.36.04
    v0.36_04 < v0.36.05

    The version.pm docs aren't entirely clear on this point, but don't seem to
    contradict it.

    The trouble is...

    v0.36.1_04 > v0.36.1

    The fourth alpha of v0.36.1 is greater than the release of v0.36.1. Which
    means you always have to do that double increment which is odd. It means the
    proper release sequence is: v0.36.0 -> v0.36.0_01 -> v0.36.1.

    It does have the benefit of being a simpler algorithm. 1) Convert _ to . 2)
    If equivalent, alpha loses.

    Anyhow, I'm not really concerned just so long as its written down, once and
    for all, and independently of version.pm.


    --
    On error resume stupid

Related Discussions

Discussion Navigation
viewthread | post
Discussion Overview
groupcpan-workers @
categoriesperl
postedApr 19, '10 at 12:38p
activeApr 20, '10 at 12:27a
posts12
users6
websitecpan.org

People

Translate

site design / logo © 2021 Grokbase