mirror of
https://github.com/semver/semver.git
synced 2026-07-11 03:53:53 -05:00
[GH-ISSUE #976] Time to solve the SemVer version ambiguity issue. #5719
Reference in New Issue
Block a user
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?
Originally created by @jwdonahue on GitHub (Sep 19, 2023).
Original GitHub issue: https://github.com/semver/semver/issues/976
Writing this to encourage discussion of two issues I hope to solve with a single PR:
As far as I can tell, prior to @mojombo 's handoff of SemVer to @haacked, every update to the SemVer document was properly versioned. Since the first 2.0.0 release, there have been many minor and patch level changes to the document without any document version bumps. I've read arguments that this practice somehow promoted stability, but I think it can be argued that SemVer 2.0.0 is in fact unstable, since documentation that pointed to the original 2.0.0 no longer points to that document at all.
There are many open pull requests in the queue, a few of which should probably be merged, but not before we solve the disambiguation problem and return to bumping the document version number. I propose that the next versioned update should be a major version bump that resolves the disambiguation problem by adding a version meta tag to the string:
This is identical to what I've already proposed for VersionMeta, but we don't have to sign-up for that explicitly, we can define those as referencing the appropriate semver.org/spec documents.
I suspect that if the new tag is required to have whitespace in front of it, then a lot of the tooling out there will simply ignore the tag and it devolves to a decoration for human consumption. In any case, I'll be happy to go author PR's for the major packaging silos to include support for this as an experimental feature for the various ecosystems to try out.
After this proposed update is merged, all future updates should be versioned appropriately. These two things will allow for minor updates that add backwards compatible features as well as major updates that really break things and allow for the evolution of version meta aware tooling to correctly parse and operate on the various syntaxes and semantics correctly.
@JohnTitor commented on GitHub (Dec 19, 2023):
I think one of the problems is that the latest content of semver.md is deployed on daily, which means any changes will be deployed without version bumps.
I've turned off the workflow until we figure out the solution of this issue.
@JohnTitor commented on GitHub (Dec 19, 2023):
We could also revert the website content to when v2.0.0 was tagged. But it may cause some confusion and I'd like to hear anyone's thoughts before doing so!
@jwdonahue commented on GitHub (Dec 19, 2023):
I don't think that would help anybody, but perhaps going back and finding the commits that are at least minor bumps to v2, tagging each of them, and then bumping the current version accordingly would help. That would also help with compiling a list of non-trivial contributors (see #905).
Hmm... I may have some time to spare...
@jwdonahue commented on GitHub (Dec 19, 2023):
We should come up with a consensus on how to track the various language versions at some point. I think we can easily come up with something like the SemVer version major.minor history (tracks the English version). Putting something together for each of the languages, down to the patch level, will take some effort. Most of the non-English versions started from different base versions and probably don't track every minor change to the English version.
@jwdonahue commented on GitHub (Dec 19, 2023):
@JohnTitor
Do we require that PR's include an appropriate manual bump to the version in the document or does that get autogenerated from a tag?
Have the translations been automated?
I haven't looked at semver.org in a long time.
@jwdonahue commented on GitHub (Dec 22, 2023):
Changes tend to pile up in https://github.com/semver/semver/blob/master/semver.md and then get carried over to semver.org in irregular batches. There were some changes to the spec/v2.0.0.md file on semver.org, with commit comments starting with "feat" that turned out to be patch level changes. By my count of actual feature additions, including a couple of breaking changes, we should be on SemVer 4.1.0 by now, but nobody screamed, so if we call them all minor bumps, we should be at 2.3.0 by now. Not very satisfying however, given the relative number of individual features added over the years, here on semver/semver.
Spelunking the commit histories, it is apparent that there were some breaking changes in the 1.y.z series, prior to the 2.0.0-RC series as well.
Based on the history of https://github.com/semver/semver.org/blob/gh-pages/spec/v2.0.0.md.
The following format is used:
Impact statement (mine)
Date, committer and commit url.
Commit message
Optional comment(s) (mine)
History:
Initial 2.0.0
2013-06-3, jeffhandley,
af6f56ae41Update to 2.0.0 RTM version of spec
Breaking change to the spec, multiple features and fixes.
2013-06-17, haacked,
f2d26dc5aeAdd latest spec changes
Adding "and MUST NOT contain leading zeroes" to clause 2 of the spec was arguably a breaking change.
Breaking change to the spec, multiple features and fixes.
2019-08-07, isaacs,
b5e2e75374Update v2.0.0 spec to match semver/semver
Changing "Build metadata SHOULD be ignored when determining version precedence" to MUST was a breaking change.
Features and fixes in the spec.
2020-06-21, github-actions[bot],
0047be8b4ffeat: Updated SemVer spec
Improved elucidation of precedence rules.
@varila81 commented on GitHub (Jan 12, 2025):
@hecazizo commented on GitHub (May 21, 2025):
@hecazizo commented on GitHub (May 21, 2025):