If the API has not settled yet, then wouldn't that mean the API is not stable?
I think what semver asks is very reasonable: Tell us when you break reverse compatibility. To do this, you can't use 0.x.x. On Thursday, September 20, 2012 12:52:44 AM UTC-7, Mariusz Nowak 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. > > 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
