[GH-ISSUE #976] Time to solve the SemVer version ambiguity issue. #4846

Open
opened 2026-06-13 13:15:13 -05:00 by GiteaMirror · 9 comments
Owner

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:

  1. There is no way to tell whether a version string is a SemVer v1, 2 or whatever is next string.
  2. There have been many updates to v2 that did not get an appropriate patch or minor level bump and that should not ever happen again.

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:

    <version> [prerelease] [buildmeta] {SemverX}
    <version> [prerelease] [buildmeta] {SemVerX.Y}

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.

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: 1. There is no way to tell whether a version string is a SemVer v1, 2 or whatever is next string. 2. There have been many updates to v2 that did not get an appropriate patch or minor level bump and that should not ever happen again. 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: ``` <version> [prerelease] [buildmeta] {SemverX} <version> [prerelease] [buildmeta] {SemVerX.Y} ``` This is identical to what I've already proposed for [VersionMeta](https://versionmeta.org), 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.
Author
Owner

@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.

<!-- gh-comment-id:1862585255 --> @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](https://github.com/semver/semver.org/actions/workflows/sync.yml) until we figure out the solution of this issue.
Author
Owner

@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!

<!-- gh-comment-id:1862793179 --> @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!
Author
Owner

@jwdonahue 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...

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...

<!-- gh-comment-id:1863389142 --> @jwdonahue 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... 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...
Author
Owner

@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.

<!-- gh-comment-id:1863412925 --> @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.
Author
Owner

@jwdonahue commented on GitHub (Dec 19, 2023):

@JohnTitor

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.

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.

<!-- gh-comment-id:1863423785 --> @jwdonahue commented on GitHub (Dec 19, 2023): @JohnTitor > 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. 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.
Author
Owner

@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, af6f56ae41

Update to 2.0.0 RTM version of spec

Breaking change to the spec, multiple features and fixes.

2013-06-17, haacked, f2d26dc5ae

Add 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, b5e2e75374

Update 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], 0047be8b4f

feat: Updated SemVer spec

Improved elucidation of precedence rules.

<!-- gh-comment-id:1867994508 --> @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, https://github.com/semver/semver.org/commit/af6f56ae41044209822f63b751f2e17b7aa03a8f #### Update to 2.0.0 RTM version of spec ## Breaking change to the spec, multiple features and fixes. ### 2013-06-17, haacked, https://github.com/semver/semver.org/commit/f2d26dc5ae8438da0609163ffb49baa4efc4a061 #### Add 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, https://github.com/semver/semver.org/commit/b5e2e75374611657c0c62e0bcc8d03172d49e3d5 #### Update 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], https://github.com/semver/semver.org/commit/0047be8b4fcf4818c7a4ff6210fbb7ea9c0a9071 #### feat: Updated SemVer spec Improved elucidation of precedence rules.
Author
Owner

@varila81 commented on GitHub (Jan 12, 2025):

Writing this to encourage discussion of two issues I hope to solve with a single PR:

  1. There is no way to tell whether a version string is a SemVer v1, 2 or whatever is next string.
  2. There have been many updates to v2 that did not get an appropriate patch or minor level bump and that should not ever happen again.

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:

    <version> [prerelease] [buildmeta] {SemverX}
    <version> [prerelease] [buildmeta] {SemVerX.Y}

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.

Writing this to encourage discussion of two issues I hope to solve with a single PR:

  1. There is no way to tell whether a version string is a SemVer v1, 2 or whatever is next string.
  2. There have been many updates to v2 that did not get an appropriate patch or minor level bump and that should not ever happen again.

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:

    <version> [prerelease] [buildmeta] {SemverX}
    <version> [prerelease] [buildmeta] {SemVerX.Y}

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.

<!-- gh-comment-id:2585648640 --> @varila81 commented on GitHub (Jan 12, 2025): > Writing this to encourage discussion of two issues I hope to solve with a single PR: > > 1. There is no way to tell whether a version string is a SemVer v1, 2 or whatever is next string. > 2. There have been many updates to v2 that did not get an appropriate patch or minor level bump and that should not ever happen again. > > 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: > > ``` > <version> [prerelease] [buildmeta] {SemverX} > <version> [prerelease] [buildmeta] {SemVerX.Y} > ``` > > This is identical to what I've already proposed for [VersionMeta](https://versionmeta.org), 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. > Writing this to encourage discussion of two issues I hope to solve with a single PR: > > 1. There is no way to tell whether a version string is a SemVer v1, 2 or whatever is next string. > 2. There have been many updates to v2 that did not get an appropriate patch or minor level bump and that should not ever happen again. > > 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: > > ``` > <version> [prerelease] [buildmeta] {SemverX} > <version> [prerelease] [buildmeta] {SemVerX.Y} > ``` > > This is identical to what I've already proposed for [VersionMeta](https://versionmeta.org), 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.
Author
Owner

@hecazizo commented on GitHub (May 21, 2025):

Writing this to encourage discussion of two issues I hope to solve with a single PR:

  1. There is no way to tell whether a version string is a SemVer v1, 2 or whatever is next string.
  2. There have been many updates to v2 that did not get an appropriate patch or minor level bump and that should not ever happen again.

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:

    <version> [prerelease] [buildmeta] {SemverX}
    <version> [prerelease] [buildmeta] {SemVerX.Y}

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.

<!-- gh-comment-id:2897500585 --> @hecazizo commented on GitHub (May 21, 2025): > Writing this to encourage discussion of two issues I hope to solve with a single PR: > > 1. There is no way to tell whether a version string is a SemVer v1, 2 or whatever is next string. > 2. There have been many updates to v2 that did not get an appropriate patch or minor level bump and that should not ever happen again. > > 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: > > ``` > <version> [prerelease] [buildmeta] {SemverX} > <version> [prerelease] [buildmeta] {SemVerX.Y} > ``` > > This is identical to what I've already proposed for [VersionMeta](https://versionmeta.org), 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. > > >
Author
Owner

@hecazizo commented on GitHub (May 21, 2025):

Writing this to encourage discussion of two issues I hope to solve with a single PR:

  1. There is no way to tell whether a version string is a SemVer v1, 2 or whatever is next string.
  2. There have been many updates to v2 that did not get an appropriate patch or minor level bump and that should not ever happen again.

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:

    <version> [prerelease] [buildmeta] {SemverX}
    <version> [prerelease] [buildmeta] {SemVerX.Y}

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.

<!-- gh-comment-id:2897501322 --> @hecazizo commented on GitHub (May 21, 2025): > Writing this to encourage discussion of two issues I hope to solve with a single PR: > > 1. There is no way to tell whether a version string is a SemVer v1, 2 or whatever is next string. > 2. There have been many updates to v2 that did not get an appropriate patch or minor level bump and that should not ever happen again. > > 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: > > ``` > <version> [prerelease] [buildmeta] {SemverX} > <version> [prerelease] [buildmeta] {SemVerX.Y} > ``` > > This is identical to what I've already proposed for [VersionMeta](https://versionmeta.org), 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. > > >
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: github-starred/semver#4846