1.0.0 is not just a number

[domenic]

From the semver spec:

Major version zero (0.y.z) is for initial development. Anything may change at any time. The public API should not be considered stable.

Before 1.0.0, the version numbers have no semantics. A patch version could introduce backward-incompatible changes. Indeed, subsequent parts of the spec explicitly state they only apply if the major version number x is > 0.

[dominictarr]

Technically, you are correct.

However, our goal here is just to explain the minimum to get npm authors not breaking other people's modules, by say, putting a breaking change into a minor version.

We don't mention the bit where versions under 1.0.0 have a special meaning, because npm doesn't handle them specially, and because we want to encourage publishing as early as possible.

I think the reason the semver spec is like that is because it fits with the way that people have traditionally used versions, so that they can easily 'port to semver'. This is not the best part of the semver spec.

We could consider this "npm flavored semver"

[domenic]

I don't think that's quite the right way of looking at it.

npm doesn't handle any version numbers specially. It's entirely up to package consumers and maintainers to give semantics to their versions, and enforce them.

Thus myself, as an Orthodox Semverist, will often make breaking changes from 0.0.1 to 0.0.2, and if I depend on any package with a version number < 1.0.0, I will pin it exactly to e.g. =0.1.2, since I know that the switch from 0.1.2 to 0.1.3 could break anything and everything.

On the other hand, the Reformed Semverists (what you explain in this repo) might say that the idea of publishing code before you lock down a public API is stupid, and so there is no need for special semantics for that case, and thus we should start at 0.0.0 instead of reserving a version range for people who make rapid changes. Those people will not make breaking changes from 0.0.1 to 0.0.2, and will pin versions at ~0.1 without worry, since they assume nobody will break things without bumping the major version, even if the major version is 0.

Finally, we have the Iconoclast Semverists. They seem believe that below 1.0.0, the minor version increments when there are breaking changes, and the patch version increments when there are new features. Thus they will pin versions at ~0.1.2, but not at ~0.1, since they think the switch from 0.1.2 to 0.2.0 could break backward compatibility, whereas 0.1.2 to 0.1.3 won't.

In my experience we have a lot of Iconoclast Semverists in the community. We have very few Orthodox Semverists, and before this repo, I'd never heard the Reformed Semverist point of view that you seem to be espousing.

Regardless, npm does not pick out any of these approaches as more or less correct. It's entirely up to the way that package consumers pin their versions using npm, and package producers publish using npm. So your Reformed Semverist approach doesn't really seem to be "npm flavored semver" as much as "don't publish code before locking down your public API-flavored semver."

[junosuarez]

guys, let's not be so strict about all of this. there's an easy way to tell a module's awesome level: https://npmjs.org/package/powerlevel

[dominictarr]

@domenic there is also at least one developer I know who NEVER uses ~, and pins everything to an exact version. A Paranoid Semverist?

So, although I like the idea of a Reformed Semverist, but I suggest that the true meaning of Reformed Serverism means that the core part of SemVer is the MAJOR.MINOR.PATCH, and that one may start publishing at 0.0.0, and whenever you make a breaking change, you bump major version, even if it was just one small thing that broke. Whether or not it was a total rewrite, that doesn't matter to the module's user.

If their module ends up as 5.6.13, then great, because they have stuck to the Sacred Semantics.

This is a great progress to some other versioning patterns, like in ubuntu distro, where the major version is just the year, or oracle db - the first release was called oracle v2, because they didn't think anyone would be stupid enough buy an oracle v1...

Some people seem to attach some sentiment to versions, and think that the difference between 1.. and 2.. just means "a whole lot".

All Semverist Sects must reject Sentimental Versioning.

I guess Reformed Semverists could avoid this agrument explicitly by always starting at 1.0.0.

[domenic]

Hah, yes, I think I know who you're talking about ;).

I understand the attraction of Reformed Semverist for its simplicity, which you do state well. However, (a) I don't know any packages that use that philosophy; (b) it's the same as Orthodox Semverist except it doesn't give you that 0.x.y window wherein you can publish things publicly while not attaching semantics to your versions.

The question, I guess, is whether that window is valuable, and more importantly, whether it should be explained in this guide. I'd say it is valuable, but it could be left as an "advanced feature" that doesn't need explanation.

[dominictarr]

All my modules are Reformist Semver.

Hmm, writing small targeted modules, I either abandon them after I realize they wern't the right idea - probably not getting past a major version... or if it turned out to be the right idea, then I probably don't change it much.

I usually don't write a new module for the same thing with the same name, I create a new module, and abandon the old one, so I'm happy as a reformed semverist.

So, if we are to make this guide compatible with orthodox semverism, (while keeping it as simple as it is) we could recommend starting at 1.0.0, or always using exact versions under 1.0.0, so, use "module": "0.x.y" but it's okay to use "module": "~1.x.y" or "module": "~1.x"

[dominictarr]

I am reluctant, though, because explaining that makes the whole thing a lot more complicated.

[domenic]

I think it could be left simple by changing the example, and replacing the two sentences about 1.0.0 with something like

"Your package should be 1.0.0 as soon as you are ready for other people to start depending on it. The period before 1.0.0 is for rapidly iterating your API, with no guarantees about the version semantics. This is helpful for code you just want to get out there, share, and collaborate on, but not so helpful for code you want others to build with."

[junosuarez]

I don't think it really adds that much cognitive overhead to explain that version numbers < 1 are "preview" releases. I think this encourages people to release earlier, as it acts as something of a safety net.

[dominictarr]

Right, so I could say "normally you should start at 1, unless your module is experimental"

However, I must say, I find the idea of semanticless versions appaling, and do not wish to encourage it.

That would just need all these "the api looks stable, please make it 1.0.0" issues.

Take https://npmjs.org/package/q for example, this look pretty stable to me, and very well documented. Is q@0.9.0 gonna be a breaking change?

[domenic]

@dominictarr yes it is; we will be removing several deprecated methods.

[dominictarr]

that is silly. make it 1.0.0

[dominictarr]

oh, from http://semver.org FAQ

How do I know when to release 1.0.0?

If your software is being used in production, it should probably already be 1.0.0. If you have a stable API on which users have come to depend, you should be 1.0.0. If you're worrying a lot about backwards compatibility, you should probably already be 1.0.0.

[junosuarez]

If your software is being used in production, it should probably already be 1.0.0.

That's a silly (and arbitrary) burden of stability for production software. It should be stable as in "not crash and burn", but there's no reason you can't have rapidly changing software in production without making claims of api stability.

Maybe if the major version number < 1 isn't well regarded, I should just be making more liberal (if less semantic) use of tags after the version number.

This post is version 1.0.1-experimental.

[max-mapper]

I think using semver as a marketing tool is silly so I just blindly increment numbers based on the 3 simple rules stated in semver-ftw. "marketing tool" meaning using 1.0.0 to convey some sort of reliability to potential users

[defunctzombie]

:fire: death to non-believers :fire:

[jugglinmike]

The goal of getting people to publish as early as possible is well-served by a "special" interpretation of pre-1.0.0 releases.

It's good for developers to get their ideas published as early as possible--it sounds like everyone agrees on the basic tenets of OSS behind this claim. There is a negative effect to this, though: module consumers have no way of determining API stability.

Adopting a module is a commitment on the part of the consumer, and I think it's fair to say they want two things:

1. The module not to break their application
2. The module to enjoy the continued support/improvements that minor and patch releases provide

For example: a 2-month-old module at version 23.0.0 is extremely unattractive to me. By committing to it, I can expect a lot of maintenance cost relative to patches that are inevitably required.

Of course, a module at 0.23.0 is no different. But at least with that version, I know what I'm getting in to. I can easily compare that module with one at 1.4.3 and determine which is more likely to work and receive support in its current form for some time. If I like 0.23.0's API and I'm just making some dumb Twitter bot, then I'll use that. But If I'm building something to hand off to a client, then I'll use 1.1.3 with reasonable expectation of support.

Without the semantic distinction of 1.0.0, I have no way of predicting the risk I take committing to a given module.

In summary: Frequently making breaking changes is great for collaboratively drafting new software, but minor and patch releases are important for module consumers. Treating 1.0.0 as "special" fosters great OSS by acknowledging both of these needs.

[defunctzombie]

I will just add that a version called 0.0.0-pre or 0.0.1-pre or 1.0.0-pre are ALL valid versions and ways to indicate development status while still being published. npm even has a facility to publish such things but not have them be the default when someone installs your module.

I think mentally, people have an idea about 1.0.0 being the "first" version of something. All I will say is that no one is to be trusted :D

[dominictarr]

@jden setting version numbers that actually represent the changes in your api is much easier than writing bug free software. At least that way, you arn't gonna break dependent programs, because they have pulled in a breaking change that looked like a patch.

[junosuarez]

@dominictarr I don't think anyone in this thread was disputing that. In @domenic's typology, adherents of both Orthodox and Reform semver preserve the meaning of minor version versus patch version.

[indexzero]

Can I be the first to say Hasidic semver?

[max-mapper]

@indexzero only if you define its views as well

[indexzero]

No no. I'll leave that up to a true believer. I'm a "just for the holidays" kind of Hasidic semver follower.

[dominictarr]

The problem here I think is that people attach special meaning to certain version numbers like 1.0.0 means that the module is in some respect "finished" or "ready". I feel that is overloading versioning with meaning, if you are happy with your module, or are committed to backwards compatibility, then say so in your documentation.

Expecting people to read between the lines (numbers) on your version is not a good way to communicate a complicated idea like this.

That is not the spirit of semver - bumping a major version just means that a breaking change has been introduced, and that dependent modules may need to be altered to be compatible with the new version.

As pointed out by @domenic in the spec it actually says that version 0 means the version is not to be taken seriously, and so the bump from 0 -> 1 does mean something.

I lament this, as I feel it introduces confusion, and encourages Sentimental Versioning.

Considering publishing SemVer@2.0.0: "The good parts". It would be a strict subset of SemVer, without the special zero range.

Note, SemVer@2.0.0 is a breaking change.

[junosuarez]

I don't see it as 1.0.0 having any special meaning, but rather the range <1.x has meaning distinct from >=1.x. This is useful for reasons outlined above in terms of encouraging releasing early and releasing often. This encouragement is not always needed!

However, it does seem to reflect my experience that most variation in a particular design comes at the beginning.

[dominictarr]

Okay, so I think there are two things we are trying to do here - strictly indicate the nature of any change between versions (breaking, feature, and bugfix changes), and to communicate the current development status of a module.

These are two different problems!

They need two different solutions!

@jugglinmike @jden @domenic what about using a semver strictly without the funny 0- range, and indicating the stability of your module in the documentation like node.js does?

Each core module in node has a stability index,

• depreciated
• experimental
• unstable
• stable
• frozen
• locked

described here http://nodejs.org/api/documentation.html

You could use a stability index for the module overall, or for individual features.

this information could even be put into the package json, and shown on npmjs.org

@izs what do you think?

[domenic]

@dominictarr I don't know why you're insistent on coming up with your own solution to a problem that is already solved by the official semver spec. Smells like NIH to me.

what about using a semver strictly without the funny 0- range,

If by this you mean "advocate never releasing packages below 1.0.0," then OK, that's fine. That sidesteps the whole debate, and from there, you can advocate anything you want for stability, and maybe people will follow you, or maybe they'll use the tools we already have.

What I don't like is advocating releasing packages below 1.0.0 with semantics different from those of semver.org. By doing so you're communicating to people that my 0.x packages will be stable and not have API changes from 0.1 to 0.2 or even from 0.1.0 to 0.1.1, which they very well might. Even Iconoclast Semverists will be hurt by such advocacy.

[dominictarr]

Okay, so I'll advocate just not using the 0 range, and starting from 1.

It seems that people want to communicate about the stability of their modules, and I think it's confusing to for major version to indicate stability.

So, what do you think about using the stability index?

[domenic]

I think it's not confusing to use the major version to indicate stability, and plan to continue to do so. Happy to let others chime in though :)

[dominictarr]

If >= 1.0.0 means "stable" and version numbers in the 0.x.y range mean nothing, then you are between a rock and a hard place, because there is no way to have an unstable module with meaningful version numbers. That is what I want.

[izs]

Look. You guys. You'll never ever settle this.

Versions mean whatever the author means by that version number. How do you know what the author meant? Read the docs, or just ask them.

This effort to reduce away that need for actual human investigation is a bit foolish. That's why npm and node-semver make no claims about what "1.0.0" means, except that it is > 0.88.67 and < 2.25.4.

Now, if Domenic want to day that 1.0.0 is when his module gives him warm fuzzy secure feelings, then great. If Dominic wants to say that 1.0.0 is simply the first breaking change, then that's also fine. If I'm using your module, I have to know how it work anyway, an knowing what the version means is only a tiny part of that.

Given how people tend to use versions, and how the "1.3.x" and ~ style comparators work, it's easier if patch versions are "pretty safe" to update to, and major version bumps are "omg rewrite", and minor versions are somewhere in between.

But we are not prescriptivist here! The ordering is defined, and the comparators are there. These are the tools by which actual humans define semantics that make sense in context. The "sem" in "semver" is what you put there. It's not in the numbers themselves. It requires understanding and trust of the author's approach. You're using their code, so you'd better trust them already, and probably read the docs at least once.

This is a social problem which cannot be solved with a technical solution, and any "1.0 means this or that" is jut propaganda to try to get other people to be like you. Which is part of the process, of course. But as this is an anarchic system, the benefit to Domenic of accepting Dominic's aberrant use of the first natural number is pretty high, so it would be wise to just get over it, and accept the difference, where it matters.

If, in the fullness of time, we abandon 1.0 magic, or change it, as we have "beg the question", then we'll just have to live with it. That's how language works, and version numbers are just a structured token in the complex language game of code reuse. They who write quality modules will decide the rules of the game.

On Saturday, March 2, 2013, Dominic Tarr wrote:

So, this is what it really boils down to for me, why I don't like the 0.x.y range rule:

It discourages module authors from using semver effectively during periods when their module is unstable.

And unstable/experimental modules are the modules that benefit most from semver!

— Reply to this email directly or view it on GitHubhttps://github.com/dominictarr/semver-ftw/issues/2#issuecomment-14342163 .

[max-mapper]

... and my axe!

[dominictarr]

a tool for inserting stability messages into your README and package.json

[junosuarez]

This issue is still showing up on my personal "open issues mentioning you" list, limiting its utility. Could you please consider closing it?

[isaacs]

+1 for closing this 2-year-old testament to defacto vs dejure specifications.