Robert Ismo's Website

The issue with Semantic Versioning

Semantic Versioning(SemVer) is a version number system that proposes a simple versioning scheme: v<MAJOR>.<MINOR>.<PATCH>[<ADDITIONAL>](I will prepend a literal v when referring to a SemVer number). Straight from their page:

  1. MAJOR version when you make incompatible API changes
  2. MINOR version when you add functionality in a backward compatible manner
  3. PATCH version when you make backward compatible bug fixes

An example of a SemVer is v1.11.3, or v0.0.3.

What is wrong here?

Semantic versioning is pretty good! It solves the issue it is looking to address, nothing is wrong here, really. However, what I feel there is a need for is a slightly different focus in what a version numbering system is meant to communicate. Currently SemVer is centered around this idea of the “API” and “incompatibility” which I have noticed are squishy and not well defined ideas. Not is the sense that you cannot have good usage of semantic versioning, but rather, bad usage of semantic versioning is particularly egregious. There are many projects, and entire ecosystems(cough javascript) that have taken this Silicon Valley “move fast and break things” apporach to their software in a way that completely bastardizes what SemVer is trying to achieve. A Major version should be a major event, also more Free and Open Source software should have LTS for their major versions and they should charge for it too.

An alternative

This isn’t a very long blog post, I will flesh it out if people have a response, but I wanted to at least get the idea out there first. I do not think you have to leave SemVer, but it is always nice to discuss better ways! I think we need a more opinionated versioning system. One that does more than just communicate a semantic idea of what a version did to a bit of software, but communicates a proper manner of consumer’s engagement with said software. This will reduce the burden on project maintainers, greatly incomparison to what SemVer asks of project maintainers. This alternative versioning is made to explicitly commuincate upgrade guidance to software consumers, packagers, distro maintainers, and end users.

The alternative I propose is also a three number scheme: w..[]. I have not named this sstem yet, but we will use a literal w to distinguish it from SemVer.

  1. UPDATE version when a bug fix or improvement is made to the API. This is nearly identical SemVer PATCH.
  2. EXPERIMENT version when you add functionality in a backward compatible manner to the RELEASE version only.
  3. RELEASE version when you are ready to present a majore update, and new support plan for the software. (explained below)

Opiniated

This is not a spec, I may make an official one in the future.

This alternative version is extremely opinionated. This is to make sure that version numbers actually communicate something real and understandable to end consumers, promoting more stable software.

  1. A project MUST be initially release as either w1.0.0 or w0.0.0.
  2. (Taken from SemVer) Once a versioned package has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version.
  3. (Taken from SemVer) 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.
  4. RELEASE version X, where X > 0, communicates that this package is ready for production use, this is extremely firm, If not ready for production, use w0.y.z.
  5. Version numbers MUST be incremented by 1. For w1.0.0 and w3.0.0 to exist w2.0.0 MUST exist. for w1.11.0 and w1.13.0 to exist w1.12.0 MUST exist. For w13.9.3 and w13.9.5 to exist w13.9.4 MUST exist.
  6. Following means to upgrade to a newer version at the first available opportunity. It is irresponsible to NOT follow UPDATE versions. It is irresponsible to follow RELEASE or EXPIRIMENT versions.
  7. A version tag of wX.Y is an alias for the most UPDATE version with RELEASE X and VERSION Y.
  8. Version wX.0.0 and a version tag of wX.0 is of special importantance. This is a stable release, most consumers should be using this version.
  9. For a variety of reasons, a consumer may want to use wX.Y.Z, where Y > 0. This is an experimental release. Experiments are there for the project maintainer to try new things, give people features they have been requesting, collect data, deprecate things, and generally prepare for the next stable release. EXPERIMENT versions should be very explicitly and intentionally upgraded to and not followed, once on an EXPERIMENT versions, you should follow it’s UPDATE versions.
  10. Support means to you are providing UPDATE versions for the stable release, Extended Support means you are providing UPDATE versions for stable release and certain of its experimental releases. Full Extended Support means you are providing UPDATE versions for stable release and all of its experimental releases that are currently in use and or not deprecated. The current Stable version should be in Full Extended Support. Generally we will use the following initialism for support regarding older stable versions: LTS(Long-Term Support), LTES(Long-Term Extended Support), LTFES(Long-Term Full Extended Support).
  11. You may use whatever LTS strategy you want for your project, however you should communicate clearly strategy to consumers.
  12. You should be consistently deprecating experiment releases that are representative of the next stable release, and especially if they do not see usage by consumers of your porject.
  13. RELEASE Versions should represent all the knowledge gathered from your experiments, and be a project you are looking to maintain and build off of in the future.