SemVer 2.0 Released

Jun 18, 2013 semver versioning suggest edit

One of the side projects I’ve been working on lately is helping to shepherd the Semantic Versioning specification (SemVer) along to its 2.0.0 release. I want to thank everyone who sent pull requests and engaged in thoughtful, critical, spirited feedback about the spec. Your involvement has made it better!

I also want to thank Tom for creating SemVer in the first place and trusting me to help move it along.

I’ve mentioned SemVer in the past as it relates to NuGet. The 2.0.0 release of SemVer addresses some of the issues I raised.

What’s Changed?

Not too much has changed. Most of the changes focus around clarifications.

Build metadata

Perhaps the biggest change is the addition of optional build metadata (what we used to call a build number). This simply allows you to add a bit of metadata to a version in a manner that’s compliant with SemVer.

The metadata does not affect version precedence. It’s analogous to a code comment.

It’s useful for internal package feeds and for being able to tie a specific version to some mechanism that generated it.

For existing package managers that choose to be SemVer 2.0 compliant, the logic change needed is minimal. Instead of reporting an error when encountering a version with build metadata, all they need to do is ignore or strip the build metadata. That’s pretty much it.

Some package managers may choose to do more with it (for internal feeds for example) but that’s up to them.

Pre-release identifiers

Pre-release labels have a little more structure to them now. For example, they can be separated into identifiers using the “.” delimiter and identifiers that only contain digits are compared numerically instead of lexically. That way, 1.0.0-rc.1 < 1.0.0-rc.11 as you might expect. See the specification for full details.

Clarifications

The rest of the changes to the specification are concerned with clarifications and resolving ambiguities. For example, we clarified that leading zeroes are not allowed in the Major, Minor, or Patch version nor in pre-release identifiers that only contain digits. This makes a canonical form for a version possible.

If you find an ambiguity, feel free to report it.

What’s Next?

As SemVer matures, we expect the specification to become a little more formal in nature as a means of removing ambiguities. One such effort underway is to include a BNF grammar for the structure of a version number in the spec. This should hopefully be part of SemVer 2.1.

Found a typo or mistake in the post? suggest edit

Comments

17 responses

distantcam • June 18th, 2013
Awesome! I've been waiting for SemVer 2 to be finalized for a while now. Do you happen to know when NuGet will be updated to support this?
haacked • June 18th, 2013
Very soon I hope. Jeff Handley has been involved in the conversation for a while now so they've been expecting this.
dominictarr • June 19th, 2013
uh, doesn't semver "2.0" imply a breaking change? then you say "not much has changed"? sounds like this should be a minor version...
Medo • June 19th, 2013
It IS a breaking change, since existing tools will have to be adapted for the addition of build metadata.
dominictarr • June 19th, 2013
Right. Build metadata was called build number before, and compared lexicographically. but now, if it's .3 (say) then the numerical portion is compared as a number, not a string.
in some cases, this changes the order of some semver versions, and so therefore this IS a breaking change.

Great. I was just confused because the text wasn't explicit enough.

Carry on!
haacked • June 19th, 2013
Build number was not in SemVer 1.0.0 at all. :)
dominictarr • June 19th, 2013
Oh, then wouldn't that make this a feature addition then? (i.e. minor)
haacked • June 19th, 2013
Well the clarifications we made could be considered breaking changes. Whereas 01.01.01 was ambiguous before and thus potentially allowed, SemVer 2.0 states that it is not.

Also, fundamentally, SemVer versioning applies to libraries and packages. It doesn't have to apply to how you market products. :)
dominictarr • June 19th, 2013
Are you saying that SemVer actually uses Sentimental Versioning?
Isaac Schlueter • June 19th, 2013
Har Har.

In SemVer 1.0, as I read the spec, "1.0.0-a.5" > "1.0.0-a.10". Now it's the reverse. That's a breaking semantic change.

In SemVer 1.0, "1.0.0+a" < "1.0.0+b". Now they're equivalent. Another breaking change.

In SemVer 1.0, the version "01.02.03" was valid. In SemVer 2.0, it is not. Another breaking change.

There's probably a few more I'm not noticing, but having rewriten node-semver to move it from v1.0 of the spec to v2.0, I can tell you, it's quite a lot of breaking stuff. The clarifications are just a bonus :)

Bumping the major version is absolutely the right call here.

> Also, fundamentally, SemVer versioning applies to libraries and packages. It doesn't have to apply to how you market products. :)

In the open source world, the line between "libraries and packages" and "marketing products" is rather vague. All version numbers are marketing, and the semantics come from humans, not from a specification.

The SemVer specification is like a dictionary. It defines a vocabulary, and describes how people tend to use the terms in it. If you want to be understood by others, it pays to follow the guidelines. But let's not indulge in prescriptivism here! It's not the role of a dictionary to define what words mean, but rather to report on the definitions that already exist and provide guidance. Terms in human brains can have subtleties of meaning that a dictionary cannot ever fully capture, try as it might.

It's the language community that defines the semantics of a language's terms, and version numbers are no different.
haacked • June 19th, 2013
> In SemVer 1.0, "1.0.0+a" < "1.0.0+b". Now they're
> equivalent. Another breaking change.

Actually, these are invalid according to SemVer 1.0.0. The build metadata wasn't added until after 1.0.0.

But yeah, I agree with everything you said here.
dominictarr • June 19th, 2013
Thanks Isaac Schlueter, that is much more clear than before - but there is one thing I must beg to differ on. SemVer is a specification. it is not a description of how people use semver, but a precise description of what semver is, so that you can judge whether any particular instance of a version number is valid semver or not.

If anything, a spec is more like legislation than a dictionary.
mdonahoe • June 20th, 2013
Is "metatada" a typo?
haacked • June 20th, 2013
It's what a meta-magician says at the end of his meta-magic trick. Meta-TADA!

Nope, you're right. It's a typo. Thanks! I fixed it.
Isaac Schlueter • June 20th, 2013
dominictarr As far as the contents of the SemVer string itself, and the ordering of versions, sure. It is a spec.

But as far as the "semantic" part, it's got a lot of fuzzy parts. Semantics come from humans. What constitutes a "breaking" change, really? Is it a "bugfix" to add a feature that was mistakenly removed, or is that "new functionality"? What if you bump the allowed version of a dependency, and this breaks someone's program that was diving into your library's guts? What about marked "private" APIs that are nonetheless exposed, and may change and cause disruption? Then there are other meaning that sometimes is communicated via version numbers, like Node's "even = stable, odd = unstable" semantics.

None of this is (or should be) in the specification. The spec, like a dictionary, tells you "If you see this specific term, here's a good guess at what the author is trying to tell you", and authors that deviate too far from the norms in the language community are deviants. But deviants, and people using things "wrong" often make permanent change in language communities! Just look at phrases like "begs the question", which have radically changed from their original meaning.
Isaac Schlueter • June 20th, 2013
Just to be clear: I'm *not* suggesting that the SemVer spec should answer all the questions ever. I'm suggesting that there will always be semantic questions that SemVer doesn't stipulate, because software is complicated, and human communication is complicateder.
dominictarr • June 21st, 2013
Right - okay - semver is only a guide at that point. Agreed.