Time to solve the SemVer version ambiguity issue.

[jwdonahue]

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.

[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.
I've turned off the workflow until we figure out the solution of this issue.

[JohnTitor]

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]

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

[jwdonahue]

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]

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

[jwdonahue]

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, semver/semver.org@af6f56a

Update to 2.0.0 RTM version of spec

Breaking change to the spec, multiple features and fixes.

2013-06-17, haacked, semver/semver.org@f2d26dc

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, semver/semver.org@b5e2e75

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], semver/semver.org@0047be8

feat: Updated SemVer spec

Improved elucidation of precedence rules.