1.0.0 is not just a number #2
Comments
|
Technically, you are correct. However, our goal here is just to explain the minimum to get npm authors not breaking other people's modules, We don't mention the bit where versions under I think the reason the semver spec is like that is because it fits with the way that people have traditionally used versions, We could consider this "npm flavored semver" |
|
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." |
|
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 |
|
@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, 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, 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 |
|
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. |
|
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 |
|
I am reluctant, though, because explaining that makes the whole thing a lot more complicated. |
|
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." |
|
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. |
|
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. |
|
@dominictarr yes it is; we will be removing several deprecated methods. |
|
that is silly. make it 1.0.0 |
|
oh, from http://semver.org FAQ How do I know when to release 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 |
|
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 |
|
🔥 death to non-believers 🔥 |
|
The goal of getting people to publish as early as possible is well-served by a "special" interpretation of pre- 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:
For example: a 2-month-old module at version Of course, a module at Without the semantic distinction of In summary: Frequently making breaking changes is great for collaboratively drafting new software, but minor and patch releases are important for module consumers. Treating |
|
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 |
|
@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. |
|
@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. |
|
Can I be the first to say Hasidic semver? |
|
@indexzero only if you define its views as well |
|
No no. I'll leave that up to a true believer. I'm a "just for the holidays" kind of Hasidic semver follower. |
|
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, 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. |
|
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. |
|
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, Each core module in node has a stability index,
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? |
|
@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.
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. |
|
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, So, what do you think about using the stability index? |
|
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 :) |
|
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. |
|
Look. You guys. You'll never ever settle this. Versions mean whatever the author means by that version number. How do you This effort to reduce away that need for actual human investigation is a Now, if Domenic want to day that 1.0.0 is when his module gives him warm Given how people tend to use versions, and how the "1.3.x" and ~ style But we are not prescriptivist here! The ordering is defined, and the This is a social problem which cannot be solved with a technical solution, If, in the fullness of time, we abandon 1.0 magic, or change it, as we have On Saturday, March 2, 2013, Dominic Tarr wrote:
|
|
... and my axe! |
|
a tool for inserting stability messages into your README and package.json |
Also things I had to do: git commit -m "Module generated by goodeggs-npm" git push --set-upstream origin master Add a project description on GitHub
Since the SemVer spec is weirdly magical about 0.x.y versions, and we cannot ever hope to get everyone to believe what the correct interpretation of 0.x versions are, let's just skip them entirely.
|
This issue is still showing up on my personal "open issues mentioning you" list, limiting its utility. Could you please consider closing it? |
|
+1 for closing this 2-year-old testament to defacto vs dejure specifications. |
From the semver spec:
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.
The text was updated successfully, but these errors were encountered: