github-starred/semver
2
0
Fork 0
mirror of https://github.com/semver/semver.git synced 2026-07-10 19:50:47 -05:00
Code Issues 1.0k Packages Projects Releases 4 Wiki Activity

[GH-ISSUE #88] Misc thoughts, mostly on pre-release versions #2779

New Issue
Closed
opened 2026-04-25 16:40:18 -05:00 by GiteaMirror · 7 comments
GiteaMirror commented 2026-04-25 16:40:18 -05:00
Owner
Copy Link

Originally created by @tbull on GitHub (Apr 18, 2013).
Original GitHub issue: https://github.com/semver/semver/issues/88

I'm about updating my implementation for the 2.0.0-rc2 version of the spec as of this commit, and I ran into some thoughts and questions while doing so. This is a lose accumulation of thoughts, combined with a request for comments. Feel free to open new issues to discuss specific matters in detail.

Q: How should prerelease/build information be handled when incrementing version numbers? (This is about how a bumpMinor() method and alike of a SemVer implementation should work. This might go into the FAQ.)
A: Drop them. And provide overloaded bump*() methods which take new prerelease/build information as arguments.
(Recommended so in https://github.com/mojombo/semver/issues/60#issuecomment-14969713, and accepted for instance by zafarkhaja in his/her implementation. I think, it's a good and simple solution.)

Q: Should a pre-release version really satisfy the requirement for the corresponding release version? For example, should pre-release version 1.4.0-rc.1 satisfy a dependency on release version 1.4.0? If yes, how could the request for a dependency be specified so that it is clear that the pre-release version is not good enough?

Opinion: The precedence rule for pre-release versions is too complicated (splitting on dots, then comparing individual segments, sometimes numerically, somtimes lexically). It violates the KISS principle and looks like a result of the committee effect. On the other hand, taking this away would mean a precedence of pre-release versions cannot be established, as it is already the case for build information now. (But do we actually need that? I think yes, at least to some extent: We should be able to assess that rc.2 is newer than rc.1. Ok, I see the point, but it's still complicated. There should at least be a "rationale" section, where such decisions are explained.)

Underspecified: How do pre-release versions with different numbers of, but otherwise identical identifiers, compare? For example, which one is greater, X.Y.Z-a.b.c or X.Y.Z-a.b.c.d?

Implementation note: Since pre-release identifiers consisting of only digits are compared numerically, the version strings X.Y.Z-rc.1 and X.Y.Z-rc.01 are semantically equal. Both strings contain the exact same version information. This means, when testing two version strings for mere equality, one cannot easily shortcut with a simple string compare. While two pre-release version strings being equal implies the version information in them is equal, too, the opposite is not true: Two pre-release version strings being UNEQUAL does NOT imply the version information in them is UNEQUAL.

Nitpicking: Is "identifier" the right word for the individual parts of pre-release version and build metadata? Wouldn't "artefact/artifact" or "segment" be more suitable, because they're more generic?

Originally created by @tbull on GitHub (Apr 18, 2013). Original GitHub issue: https://github.com/semver/semver/issues/88 I'm about updating my implementation for the 2.0.0-rc2 version of the spec as of [this commit](https://github.com/mojombo/semver/blob/eceeff12c56e014a2457310a31447fb38d226761/semver.md), and I ran into some thoughts and questions while doing so. This is a lose accumulation of thoughts, combined with a request for comments. Feel free to open new issues to discuss specific matters in detail. **Q:** How should prerelease/build information be handled when incrementing version numbers? (This is about how a bumpMinor() method and alike of a SemVer implementation should work. This might go into the FAQ.) **A:** Drop them. And provide overloaded bump*() methods which take new prerelease/build information as arguments. (Recommended so in https://github.com/mojombo/semver/issues/60#issuecomment-14969713, and accepted for instance by zafarkhaja in [his/her implementation](https://github.com/zafarkhaja/java-semver). I think, it's a good and simple solution.) **Q:** Should a pre-release version really satisfy the requirement for the corresponding release version? For example, should pre-release version 1.4.0-rc.1 satisfy a dependency on release version 1.4.0? If yes, how could the request for a dependency be specified so that it is clear that the pre-release version is not good enough? **Opinion:** The precedence rule for pre-release versions is too complicated (splitting on dots, then comparing individual segments, sometimes numerically, somtimes lexically). It violates the [KISS principle](http://en.wikipedia.org/wiki/KISS_principle) and looks like a result of the [committee effect](http://en.wikipedia.org/wiki/Design_by_committee). On the other hand, taking this away would mean a precedence of pre-release versions cannot be established, as it is already the case for build information now. (But do we actually need that? I think yes, at least to some extent: We should be able to assess that rc.2 is newer than rc.1. Ok, I see the point, but it's still complicated. There should at least be a "rationale" section, where such decisions are explained.) **Underspecified:** How do pre-release versions with different numbers of, but otherwise identical identifiers, compare? For example, which one is greater, X.Y.Z-a.b.c or X.Y.Z-a.b.c.d? **Implementation note:** Since pre-release identifiers consisting of only digits are compared numerically, the version strings X.Y.Z-rc.1 and X.Y.Z-rc.01 are semantically equal. Both strings contain the exact same version information. This means, when testing two version strings for mere equality, one cannot easily shortcut with a simple string compare. While two pre-release version strings being equal implies the version information in them is equal, too, the opposite is not true: Two pre-release version strings being UNEQUAL does NOT imply the version information in them is UNEQUAL. **Nitpicking:** Is "identifier" the right word for the individual parts of pre-release version and build metadata? Wouldn't "artefact/artifact" or "segment" be more suitable, because they're more generic?
GiteaMirror commented 2026-04-25 16:40:19 -05:00
Author
Owner
Copy Link

@tbull commented on GitHub (Apr 25, 2013):

Underspecified: Are zero-length pre-release/build identifiers allowed? In the example X.Y.Z+abc..def the build information consists of three identifiers: "abc", "", "def". The spec in its current state does not rule that out, it seems.

Identifiers MUST comprise only ASCII alphanumerics and hyphen [0-9A-Za-z-].
Note that there is also an issue which deals with string lengths in general: #79

<!-- gh-comment-id:17033135 --> @tbull commented on GitHub (Apr 25, 2013): **Underspecified:** Are zero-length pre-release/build identifiers allowed? In the example X.Y.Z+abc..def the build information consists of three identifiers: "abc", "", "def". The spec in its current state does not rule that out, it seems. > Identifiers MUST comprise only ASCII alphanumerics and hyphen [0-9A-Za-z-]. > Note that there is also an issue which deals with string lengths in general: #79
GiteaMirror commented 2026-04-25 16:40:19 -05:00
Author
Owner
Copy Link

@jeffhandley commented on GitHub (Apr 30, 2013):

Thanks for these great notes!

I too have wondered about the complicated pre-release versions. I suspect we'd get along just fine if pre-release labels were just sorted alphanumerically. Tough call though.

I cannot comment on the methods for an implementation--I've been focused more on the consumption of these version numbers rather than the production of them. I will have to leave that topic to others to comment on.

The issue about different string representations of the same version number should be addressed. For numeric segments (major, minor, patch, and pre-release numeric portions) must have a canonical form defined such that comparison is always based on the canonical form.

I think the pre-release and numeric segments' canonical forms should be tidied up before we lock down v2.0.0 RTM of the spec.

<!-- gh-comment-id:17219826 --> @jeffhandley commented on GitHub (Apr 30, 2013): Thanks for these great notes! I too have wondered about the complicated pre-release versions. I suspect we'd get along just fine if pre-release labels were just sorted alphanumerically. Tough call though. I cannot comment on the methods for an implementation--I've been focused more on the consumption of these version numbers rather than the production of them. I will have to leave that topic to others to comment on. The issue about different string representations of the same version number should be addressed. For numeric segments (major, minor, patch, and pre-release numeric portions) must have a canonical form defined such that comparison is always based on the canonical form. I think the pre-release and numeric segments' canonical forms should be tidied up before we lock down v2.0.0 RTM of the spec.
GiteaMirror commented 2026-04-25 16:40:20 -05:00
Author
Owner
Copy Link

@Tieske commented on GitHub (Apr 30, 2013):

Q: Should a pre-release version really satisfy the requirement for the corresponding release version? For example, should pre-release version 1.4.0-rc.1 satisfy a dependency on release version 1.4.0? If yes, how could the request for a dependency be specified so that it is clear that the pre-release version is not good enough?

Opinion: The precedence rule for pre-release versions is too complicated (splitting on dots, then comparing individual segments, sometimes numerically, somtimes lexically). It violates the KISS principle and looks like a result of the committee effect. On the other hand, taking this away would mean a precedence of pre-release versions cannot be established, as it is already the case for build information now. (But do we actually need that? I think yes, at least to some extent: We should be able to assess that rc.2 is newer than rc.1. Ok, I see the point, but it's still complicated. There should at least be a "rationale" section, where such decisions are explained.)

It is somewhat complicated but it allows for great flexibility in designing your own pre-release tags while still providing very clear presedence rules.

regarding satisfying dependencies, there is no 'binary' compatibility, it's yes, no, or maybe, see this comment

<!-- gh-comment-id:17257010 --> @Tieske commented on GitHub (Apr 30, 2013): > Q: Should a pre-release version really satisfy the requirement for the corresponding release version? For example, should pre-release version 1.4.0-rc.1 satisfy a dependency on release version 1.4.0? If yes, how could the request for a dependency be specified so that it is clear that the pre-release version is not good enough? > > Opinion: The precedence rule for pre-release versions is too complicated (splitting on dots, then comparing individual segments, sometimes numerically, somtimes lexically). It violates the KISS principle and looks like a result of the committee effect. On the other hand, taking this away would mean a precedence of pre-release versions cannot be established, as it is already the case for build information now. (But do we actually need that? I think yes, at least to some extent: We should be able to assess that rc.2 is newer than rc.1. Ok, I see the point, but it's still complicated. There should at least be a "rationale" section, where such decisions are explained.) It is somewhat complicated but it allows for great flexibility in designing your own pre-release tags while still providing very clear presedence rules. regarding satisfying dependencies, there is no 'binary' compatibility, it's yes, no, or maybe, see [this comment](https://github.com/mojombo/semver/pull/30#issuecomment-17256225)
GiteaMirror commented 2026-04-25 16:40:20 -05:00
Author
Owner
Copy Link

@haacked commented on GitHub (May 6, 2013):

Interesting observations and questions! Just a few comments.

Underspecified: Are zero-length pre-release/build identifiers allowed? In the example X.Y.Z+abc..def the build information consists of three identifiers: "abc", "", "def". The spec in its current state does not rule that out, it seems.

They are not allowed. The empty character doesn't match the provided regex [0-9A-Za-z-]. I don't think this has been the source of much confusion so far, but it wouldn't hurt to make it more clear. Please submit a PR with wording that makes this unambiguous. Ideally in a terse but concise manner. :)

<!-- gh-comment-id:17506227 --> @haacked commented on GitHub (May 6, 2013): Interesting observations and questions! Just a few comments. > Underspecified: Are zero-length pre-release/build identifiers allowed? In the example X.Y.Z+abc..def the build information consists of three identifiers: "abc", "", "def". The spec in its current state does not rule that out, it seems. They are not allowed. The empty character doesn't match the provided regex `[0-9A-Za-z-]`. I don't think this has been the source of much confusion so far, but it wouldn't hurt to make it more clear. Please submit a PR with wording that makes this unambiguous. Ideally in a terse but concise manner. :)
GiteaMirror commented 2026-04-25 16:40:21 -05:00
Author
Owner
Copy Link

@haacked commented on GitHub (May 6, 2013):

The precedence rule for pre-release versions is too complicated (splitting on dots, then comparing individual segments, sometimes numerically, somtimes lexically). I

I think this was done to keep comparisons logical when looking at segments with just numbers.

For example, let's take a simple version number without pre-release.

It's clear that 1.0.0 < 10.0.0

But now let's add pre-release into the mix. Logically we'd expect:

1.0.0-rc.1 < 1.0.0-rc.10

But if we sorted that lexicographically, the opposite would be true.

In any case, this has been this way from the beginning (and was not designed by committee), it would introduce a major breaking change, it doesn't solve any dire problems to change it, so I don't think it needs to change.

<!-- gh-comment-id:17506508 --> @haacked commented on GitHub (May 6, 2013): > The precedence rule for pre-release versions is too complicated (splitting on dots, then comparing individual segments, sometimes numerically, somtimes lexically). I I think this was done to keep comparisons logical when looking at segments with just numbers. For example, let's take a simple version number without pre-release. It's clear that `1.0.0` < `10.0.0` But now let's add pre-release into the mix. Logically we'd expect: `1.0.0-rc.1` < `1.0.0-rc.10` But if we sorted that lexicographically, the opposite would be true. In any case, this has been this way from the beginning (and was not designed by committee), it would introduce a major breaking change, it doesn't solve any dire problems to change it, so I don't think it needs to change.
GiteaMirror commented 2026-04-25 16:40:22 -05:00
Author
Owner
Copy Link

@haacked commented on GitHub (May 6, 2013):

Underspecified: How do pre-release versions with different numbers of, but otherwise identical identifiers, compare? For example, which one is greater, X.Y.Z-a.b.c or X.Y.Z-a.b.c.d?

I believe this is clear from the example provided in section 11.

Example: 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0.

Note that 1.0.0-alpha is less than 1.0.0-alpha.1. I believe this aligns with what people would normally expect. If you think this should be clarified further, please submit a PR with proposed wording. Thanks!

<!-- gh-comment-id:17506713 --> @haacked commented on GitHub (May 6, 2013): > Underspecified: How do pre-release versions with different numbers of, but otherwise identical identifiers, compare? For example, which one is greater, X.Y.Z-a.b.c or X.Y.Z-a.b.c.d? I believe this is clear from the example provided in section 11. > Example: 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0. Note that `1.0.0-alpha` is less than `1.0.0-alpha.1`. I believe this aligns with what people would normally expect. If you think this should be clarified further, please submit a PR with proposed wording. Thanks!
GiteaMirror commented 2026-04-25 16:40:23 -05:00
Author
Owner
Copy Link

@haacked commented on GitHub (May 6, 2013):

I'm going to close this as I believe all the questions have been answered. I don't think there's anything in here that urgently requires SemVer to be updated, but I'd be happy to look at PRs for suggested improvements that were proposed in this discussion. Thanks! 🌴

<!-- gh-comment-id:17506891 --> @haacked commented on GitHub (May 6, 2013): I'm going to close this as I believe all the questions have been answered. I don't think there's anything in here that urgently requires SemVer to be updated, but I'd be happy to look at PRs for suggested improvements that were proposed in this discussion. Thanks! :palm_tree:
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
consensus seeking
duplicate
extend
layout
pull-request
Mirrored from GitHub Pull Request
 question
RFC
spelling/grammar
staled
update
waiting for PR
won't fix
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
GiteaMirror ninjasurge
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: github-starred/semver#2779
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?