SemVer 2.0 composer packages

Created on 23 February 2022, over 2 years ago
Updated 9 February 2023, over 1 year ago

Problem/Motivation

Currently the pre-release version numbers are using SemVer 1.0. It would be nice to switch to SemVer 2.0.

Mainly that means there should be a dot between the pre-release tag (alpha, beta, rc, dev) and the number,
for example 1.1.1-rc1 should be 1.1.1-rc.1

The other SemVer 2.0 constraint seems to be, that major can't be zero. For example 0.1.1 is an invalid version. But this is probably solved already on packages.drupal.org.

https://semver.org/

Steps to reproduce

Proposed resolution

Remaining tasks

- Check if composer correctly handles switching to SemVer2, for example
1.1.1.beta2 < 1.1.1.beta.10
1.1.1.beta10 > 1.1.1.beta.2

- Check if update status module is impacted by this change. It should not be, as semver is not implemented in Drupal.org packaging script.

User interface changes

API changes

Data model changes

✨ Feature request
Status

Postponed

Version

1.0

Component

Code

Created by

πŸ‡­πŸ‡ΊHungary Pasqualle πŸ‡­πŸ‡Ί Budapest

Live updates comments and jobs are added and updated live.
Sign in to follow issues

Comments & Activities

Not all content is available!

It's likely this issue predates Contrib.social: some issue and comment data are missing.

  • πŸ‡³πŸ‡±Netherlands Kingdutch

    Just saw this issue linked in Slack and I believe the following part of the Issue Summary is incorrect:

    The other SemVer 2.0 constraint seems to be, that major can't be zero. For example 0.1.1 is an invalid version. But this is probably solved already on packages.drupal.org.

    I suspect this confusion comes from the following sentence on semver.org

    2. A normal version number MUST take the form X.Y.Z where X, Y, and Z are non-negative integers, and MUST NOT contain leading zeroes. X is the major version, Y is the minor version, and Z is the patch version. Each element MUST increase numerically. For instance: 1.9.0 -> 1.10.0 -> 1.11.0.

    Which talks about leading zeroes i.e. 01.0.0, 1.02.03 and so forth. However this applies to the specific parts X, Y, and Z and not the version as a whole. Additionally the following specifically demonstrates the case of 0.y.z versions

    Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.

    So in SemVer 2 the major can still be 0.

  • πŸ‡³πŸ‡±Netherlands Kingdutch

    Additionally (and this is more open to debate than my previous question and may require asking for clarification from the SemVer 2 maintainers), in my reading of the SemVer rules 1.0.0-alpha1 would be just as valid as 1.0.0-alpha.1 even though the former is not shown as examples while the latter is.

    I gather this from the following texts:

    9. A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.--.

    This states that we have a part after the X.Y.Z version which MUST be followed by a hyphen and then separators ("denoted by appending a hyphen and a series of dot separated identifiers"). i.e. X.Y.Z-IDENT1.IDENT2.IDENT3.IDENTN

    The constraint for the identifiers is "Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty.". This already suggests that they can be mixed as the language does not impose any "either alphabet characters or numerical characters and no mixing" limitation.

    This can also be confirmed by the "Backus–Naur Form Grammar for Valid SemVer Versions" at the bottom which has the following relevant parts:

    <pre-release identifier> ::= <alphanumeric identifier>
                               | <numeric identifier>
    
    <alphanumeric identifier> ::= <non-digit>
                                | <non-digit> <identifier characters>
                                | <identifier characters> <non-digit>
                                | <identifier characters> <non-digit> <identifier characters>
    
    <numeric identifier> ::= "0"
                           | <positive digit>
                           | <positive digit> <digits>
    
    <identifier characters> ::= <identifier character>
                              | <identifier character> <identifier characters>
    
    <identifier character> ::= <digit>
                             | <non-digit>
    
    <non-digit> ::= <letter>
                  | "-"
    
    <digits> ::= <digit>
               | <digit> <digits>
    
    <digit> ::= "0"
              | <positive digit>
    
    <positive digit> ::= "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
    
    <letter> ::= "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J"
               | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T"
               | "U" | "V" | "W" | "X" | "Y" | "Z" | "a" | "b" | "c" | "d"
               | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n"
               | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x"
               | "y" | "z"
    

    A prerelease identifier may be fully numeric, below we'll look at alphanumeric identifiers which are combinations of letters and numbers.

    1. We can see here we allow a non-digit, which is any letter lower or uppercase (e.g. A, a, f)
    2. We allow non-digit followed by identifier characters, an identifier character can be any digit (0-9) or non-digit (a-zA-Z\-) (e.g. a1, alpha1, beta2, gamma-0, beta)
    3. Any identifier character followed by a non digit (e.g. 1a, aa, AA, 1alpha). The identifier character can be a digit or non-digit, it just must end in a letter or hyphen (non-digit).
    4. Finally any identifier characters followed by a non-digit followed by any other identifier characters such as (0123a02341<code>, <code>01234alphaBETA), this has quite a lot of freedom. Note that also since an identifier character can be a digit and a digit may be zero, as long as the prerelease identifier contains a letter (i.e. is not fully numeric) it may start with a leading 0, this accomodates hashes and git commits where a leading zero may be significant.

    Unless I'm missing something here I'd say that Drupal's current versioning are still allowed in a compliant implementation of SemVer 2

  • πŸ‡­πŸ‡ΊHungary Pasqualle πŸ‡­πŸ‡Ί Budapest

    Yes, you are right on both cases. The major can be 0 and the pre-release tag can be almost anything.

    But,
    - some automated tools do not recommend using 0 as major, you might have problems with those.
    And the real life issue with that: https://www.youtube.com/watch?v=tc2UgG5L7WM&t=412s

    - in semver2 the pre-release tag order is specified as

    Precedence for two pre-release versions with the same major, minor, and patch version MUST be determined by comparing each dot separated identifier from left to right until a difference is found as follows:
    - Identifiers consisting of only digits are compared numerically.
    - Identifiers with letters or hyphens are compared lexically in ASCII sort order.
    ...

    That means in semver2: 1.0.0-beta9 > 1.0.0-beta10. Our current pre-release tag order is wrong by semver2.

  • πŸ‡³πŸ‡±Netherlands Kingdutch

    But,
    - some automated tools do not recommend using 0 as major, you might have problems with those.
    And the real life issue with that: https://www.youtube.com/watch?v=tc2UgG5L7WM&t=412s

    That feels more like an issue with "we choose to follow a standard and some tools don't follow that standard" and "humans are bad at following instructions or do not follow a standard t all", which I suppose is more a philosophical discussion than a tech one.

    I'd personally be annoyed if my Drupal.org projects can't be on `0.y.z` anymore because it's a good way to indicate "use this at your own risk". The video you linked flags that projects never make it to the 1.0.0 stage, but I feel like forcing people to start at 1.0.0 doesn't save that, because then I'll just adopt SemVer at 2.0.0 instead, which leads to more support work overall.

    That means in semver2: 1.0.0-beta9 > 1.0.0-beta10. Our current pre-release tag order is wrong by semver2.

    That's absolutely fair, that would mean we require the "dot" as an extra separator.

Production build 0.69.0 2024