On Sep 20, 2012 3:52 AM, "Mariusz Nowak" <[email protected]> wrote: > > Austin, version v0.x doesn't mean that project is not *stable*, in my point of view everything published on npm should be stable (unstable should just stay on github, or be published under different dedicated minor version, like node does: even numbered stable, odd numbered experimental) > > Version v0.x just means that's it's API has not settled yet and it can change breaking backwards compatibility. It's exactly the reason why Node.js is not yet 1.x, and it's up to semver rules.
+1 Everything we do at Bocoup follows the path that Mariusz has indicated. It might be "wrong" but I'd argue that it's become the defacto standard Rick > > On Thursday, September 20, 2012 3:43:31 AM UTC+2, Austin William Wright wrote: >> >> I've noticed that quite a lot of Node.js packages are tagging version number zero for all their releases: 0.4.0, 0.9.9, 0.0.1, 0.27.4, etc (to pick from packages that I use). It's as if people think that if the program is not fully feature-complete, they shouldn't release version 1.0.0. >> >> You need not feel this way! Semver <http://semver.org/spec/v1.0.0.html> >> exists so that, in addition to providing a unique ID for each release, we can infer some basic facts about the compatibility of the release, in comparison to other releases. It doesn't mean your code has all the features you want, it doesn't mean it has any standard of quality, it doesn't even mean "beta" or "production-ready". All semver asks you to do is (1) tell us when you break reverse-compatibility of your public API, (2) tell us when you release a new feature, and (3) tell us when you patch a particular bug. If you use major version zero, we lose all of this information. By definition, major version zero carries no semantics whatsoever. ~0 (major version zero) is supposed to be used for internal development and quick iteration where nearly every change breaks of the public API. However, if you're releasing software publicly, your users expect some stability in your public API. The series of releases that are stable against one another should carry the same nonzero major revision number, like "1.x.x". If you accidentally make a change that breaks, then just release a bugfix release for the breakage, and optionally release a new major version that carries the breakage. >> >> If you don't identify when you break your public API, then developers have to manually figure out which releases are breaking, and which are safe to upgrade to. We may have to carefully examine changelogs and create and run unit tests. This wastes developer time. It's also makes it hard to future-proof releases: If I know that 1.0.0 is compatible with my application, then so should 1.3.1, and any ~1 version. Unit tests are not a replacement for the major version number: When picking an appropriate package version to update to, developers (or automated programs) do not have access to changelogs or the source code to run unit tests on (nor should they). (There's also the corollary, version numbers are not a replacement for unit tests, of course.) Nor can per-module or per-function version numbers replace a package-wide version number. These sub-versions may be a good idea, but they do not tell us anything about which version of a package, something installed as a coherent whole, should be installed. >> >> Node.js itself is still releasing major version zero. This is unacceptable for all the same reasons. Node.js should be releasing 1.0.0 right now (and actually, a long while ago). Then, when a new feature is added (major change of an internal library, new core library, etc), increment the minor version number. If it breaks reverse-compatibility (crypto finally starts using buffers, say), increment the major revision number. It might be a minor breakage, in which case we can run all our tests and ensure it's no change that breaks the program, and then we can say "My program is compatible with Node.js ~2 as well as ~1.2". There is nothing so special about any feature like libuv that its release can't be marked with 2.0.0 instead, it's just a number that tells us something broke. It doesn't mean it's conforming to any release schedule, it doesn't mean it's feature complete. >> >> Having "stable" and "unstable" branches is fine for Git development, however having stable/unstable version numbers is not: The stable branch should get it's own major version number. Unstable branches would be release candidates for the next major version number: 4.0.0-a1, 4.0.0-a4, 4.0.0-rc1, etc. (Of course this numbering scheme should be avoided in production for all the same reasons, it doesn't mean anything, it's just a period of rapid iteration and API breakage.) >> >> It's just a number, numbers are cheap. If you need to make a dozen consecutive, breaking releases, then simply number them accordingly, 3.0.0 through 14.0.0. That's how semver works! >> >> Who else has encountered problems with packages breaking the semantic versioning scheme and reverse compatibility? >> >> Austin Wright. > > -- > Job Board: http://jobs.nodejs.org/ > Posting guidelines: https://github.com/joyent/node/wiki/Mailing-List-Posting-Guidelines > You received this message because you are subscribed to the Google > Groups "nodejs" group. > To post to this group, send email to [email protected] > To unsubscribe from this group, send email to > [email protected] > For more options, visit this group at > http://groups.google.com/group/nodejs?hl=en?hl=en -- Job Board: http://jobs.nodejs.org/ Posting guidelines: https://github.com/joyent/node/wiki/Mailing-List-Posting-Guidelines You received this message because you are subscribed to the Google Groups "nodejs" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/nodejs?hl=en?hl=en
