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?
diamondma...@users.sourceforge.net> 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?
On Wednesday, September 19, 2012 11:09:56 PM UTC-7, Mark Hahn wrote:
> > Who else has encountered problems with packages breaking the semantic > versioning scheme
> Not me. I didn't know any of my packages were using this scheme. Is it > widely adopted?
> On Wed, Sep 19, 2012 at 6:43 PM, Austin William Wright < > diamon...@users.sourceforge.net <javascript:>> 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, 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?
On Sep 20, 2012 3:52 AM, "Mariusz Nowak" <mari...@medikoo.com> 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.
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
> You received this message because you are subscribed to the Google
> Groups "nodejs" group.
> To post to this group, send email to nodejs@googlegroups.com
> To unsubscribe from this group, send email to
> nodejs+unsubscribe@googlegroups.com
> For more options, visit this group at
> http://groups.google.com/group/nodejs?hl=en?hl=en
The instructions you link to say "Version must be parseable by
node-semver". My 0.x releases were parseable by semver. Also those
instructions use the example "0.1.2-7 > 0.1.2-7-beta". So forgive me if I
didn't know there were rules forbidding 0.x versions in npm.
Instead of telling us what to do, you could have just suggested that we
follow the semver philosophy at the semver link. Cajoling works better
than preaching.
Unfortunately I think your suggestion will fall on deaf ears. I myself,
and I suspect most others on this list, have used the old standard 0.x for
many years and would be hard-pressed to change.
On Thu, Sep 20, 2012 at 12:40 AM, Austin William Wright <
> On Wednesday, September 19, 2012 11:09:56 PM UTC-7, Mark Hahn wrote:
>> > Who else has encountered problems with packages breaking the semantic
versioning scheme
>> Not me. I didn't know any of my packages were using this scheme. Is it
widely adopted?
>> On Wed, Sep 19, 2012 at 6:43 PM, Austin William Wright <
diamon...@users.sourceforge.net> 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.
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
>>> You received this message because you are subscribed to the Google
>>> Groups "nodejs" group.
>>> To post to this group, send email to nod...@googlegroups.com
>>> To unsubscribe from this group, send email to
>>> nodejs+un...@googlegroups.com
>>> For more options, visit this group at
>>> http://groups.google.com/group/nodejs?hl=en?hl=en
> You received this message because you are subscribed to the Google
> Groups "nodejs" group.
> To post to this group, send email to nodejs@googlegroups.com
> To unsubscribe from this group, send email to
> nodejs+unsubscribe@googlegroups.com
> For more options, visit this group at
> http://groups.google.com/group/nodejs?hl=en?hl=en
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?
Maybe. I'm just saying the odds of it's requirements being widely adopted
are slim to none. I don't think many developers have noticed any problem
using 0.x.
I shouldn't be so negative though. Feel free to evangelize. I'll shut up.
On Thu, Sep 20, 2012 at 11:10 AM, Austin William Wright <
diamondma...@users.sourceforge.net> wrote:
> 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<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?
My experience with the node community has been that we love semver,
but have a slightly different definition than what's on the website.
If an npm module release is a bug-fix then the last digit is
incremented. If it's a API breaking change, then the middle digit is
incremented and the last digit is reset. If it's an architectural
change then the first digit it adjusted. Versions starting with
0.x.y simply mean the project is young and growing. To convert
node-community-style semver numbers to "official" semver numbers, use
this table.
0.0.x -> 0.0.x
x.y.z -> (x + 1).y.z
So 0.3.14 would be 1.3.14 and 0.0.14 would stay 0.0.14.
Should we *force* everyone in the community to change our numbering
scheme to match what's on the website? I don't think so. Node has a
long history of not following existing standards strictly.
Feel free to evangelize it and explain why it's better, but it's
dishonest to say that our de-facto system is worthless simply because
it's different. That kind of approach won't convince many people I'm
afraid.
On Thu, Sep 20, 2012 at 1:16 PM, Mark Hahn <m...@hahnca.com> wrote:
>> I think what semver asks is very reasonable
> Maybe. I'm just saying the odds of it's requirements being widely adopted
> are slim to none. I don't think many developers have noticed any problem
> using 0.x.
> I shouldn't be so negative though. Feel free to evangelize. I'll shut up.
> On Thu, Sep 20, 2012 at 11:10 AM, Austin William Wright
> <diamondma...@users.sourceforge.net> wrote:
>> 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?
Library developers don't have any problem sticking with their current scheme, it's not asking anything of them.
The problem comes in when I or other developers want to *use* those libraries, and keep them up-to-date. You can't use features like "~1". And this isn't just some nifty feature I'm proposing (though I would encourage it's adoption regardless), this is a *core function of npm.*
Almost no one has a problem building a program that works *now*. But can you build a program that works a year into the future? Unfortunately it's difficult to convince people why future-proofing code is so important.
On Thursday, September 20, 2012 11:17:13 AM UTC-7, Mark Hahn wrote:
> > I think what semver asks is very reasonable
> Maybe. I'm just saying the odds of it's requirements being widely adopted > are slim to none. I don't think many developers have noticed any problem > using 0.x.
> I shouldn't be so negative though. Feel free to evangelize. I'll shut up.
> On Thu, Sep 20, 2012 at 11:10 AM, Austin William Wright < > diamon...@users.sourceforge.net <javascript:>> wrote:
>> 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 <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?
On Thu, Sep 20, 2012 at 2:27 PM, Austin William Wright <
diamondma...@users.sourceforge.net> wrote:
> The problem comes in when I or other developers want to *use* those
> libraries, and keep them up-to-date. You can't use features like "~1".
You know when you're using a module that's in a 0.x release cycle, so just
use ~0.y.z and you'll be fine.
Perhaps this is how it has come to be used, but unfortunately "young and growing" doesn't tell me anything useful about a project once I begin using it. Nor is "architectural change" versus "breaking change" a distinction that an application cares about.
Also if you use the minor version number to mean some sort of breakage, then you have no way of indicating that your application depends on a particular feature. Maybe a dependency on some new syntax sugar was introduced in 1.3.0, then you say your application depends on "~1.3".
If you want to tell an application developer something *actually useful*, tell us when you break your public API. This isn't hard to do, you just have to break the notion that the major version number means anything about maturity.
On Thursday, September 20, 2012 11:24:42 AM UTC-7, Tim Caswell wrote:
> My experience with the node community has been that we love semver, > but have a slightly different definition than what's on the website.
> If an npm module release is a bug-fix then the last digit is > incremented. If it's a API breaking change, then the middle digit is > incremented and the last digit is reset. If it's an architectural > change then the first digit it adjusted. Versions starting with > 0.x.y simply mean the project is young and growing. To convert > node-community-style semver numbers to "official" semver numbers, use > this table.
> 0.0.x -> 0.0.x > x.y.z -> (x + 1).y.z
> So 0.3.14 would be 1.3.14 and 0.0.14 would stay 0.0.14.
> Should we *force* everyone in the community to change our numbering > scheme to match what's on the website? I don't think so. Node has a > long history of not following existing standards strictly.
> Feel free to evangelize it and explain why it's better, but it's > dishonest to say that our de-facto system is worthless simply because > it's different. That kind of approach won't convince many people I'm > afraid.
> On Thu, Sep 20, 2012 at 1:16 PM, Mark Hahn <ma...@hahnca.com <javascript:>> > wrote: > >> I think what semver asks is very reasonable
> > Maybe. I'm just saying the odds of it's requirements being widely > adopted > > are slim to none. I don't think many developers have noticed any > problem > > using 0.x.
> > I shouldn't be so negative though. Feel free to evangelize. I'll shut > up.
> > On Thu, Sep 20, 2012 at 11:10 AM, Austin William Wright > > <diamon...@users.sourceforge.net <javascript:>> wrote:
> >> 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?
By this formula, Node has been 1.0+ since day one and never broken
backwards compatibility... Its understandable that young projects
hover below 1.0 in order to get a more throughly designed API in place
(and maybe fix/remove API kinks that were bad ideas at one point in
time)... but some would say that 3+ years is kinda pushing that safety
net for such a largely used project...
Essentially anyone familiar with semver would be leery of using Node
for a large scale application with the lack of guarantee in backwards
compatibility (or they should be without better explanation of the
"Node way" of doing things).
On Thu, Sep 20, 2012 at 1:24 PM, Tim Caswell <t...@creationix.com> wrote:
> To convert
> node-community-style semver numbers to "official" semver numbers, use
> this table.
> 0.0.x -> 0.0.x
> x.y.z -> (x + 1).y.z
> So 0.3.14 would be 1.3.14 and 0.0.14 would stay 0.0.14.
I was going to suggest some version numbers that Node.js could have gone with, but it's not really my place to say something like that. However, Node.js appears to have largely ended it's rapid-breakage phase around 0.4.0 at the latest.
There hasn't been any major overhauls, however I've still come across three breakages: Change in handling of buffers, changes in http/https and some related crypto and certificate changes, and biggest of all, a change in process.on('exit') that completely and totally breaks programs that used 'child_process'. I think there was also a change in process.nextTick that broke some programs. Now maybe some of these were a part of larger bugfixes, and the developers didn't realize it broke programs. But even still, that doesn't stop you from updating the version number accordingly.
Also note that many of these occurred often in the *very middle* of an otherwise "stable" release. There's just no way to guess that 0.8.4 introduced a breaking change, without knowing what the change was, and where it occurred. This is exactly the sort of problem I'm talking about that wastes developer time.
On Thursday, September 20, 2012 11:37:27 AM UTC-7, Karl Tiedt wrote:
> By this formula, Node has been 1.0+ since day one and never broken > backwards compatibility... Its understandable that young projects > hover below 1.0 in order to get a more throughly designed API in place > (and maybe fix/remove API kinks that were bad ideas at one point in > time)... but some would say that 3+ years is kinda pushing that safety > net for such a largely used project...
> Essentially anyone familiar with semver would be leery of using Node > for a large scale application with the lack of guarantee in backwards > compatibility (or they should be without better explanation of the > "Node way" of doing things).
> -Karl Tiedt
> On Thu, Sep 20, 2012 at 1:24 PM, Tim Caswell <t...@creationix.com<javascript:>> > wrote:
> > To convert > > node-community-style semver numbers to "official" semver numbers, use > > this table.
> > 0.0.x -> 0.0.x > > x.y.z -> (x + 1).y.z
> > So 0.3.14 would be 1.3.14 and 0.0.14 would stay 0.0.14.
For what it's worth, I see the value in using all three numbers to
their fullest potential as the spec describes.
Also I explained my usage of node-style semver incorrectly and I apologize.
My personal standard is I bump the last digit for both bug fixes and
feature additions. Basically any change that won't break any code
that depends on my library. I bump the middle number when I make a
breaking change. So basically it's like the official semver except
the first digit is 0 forever (nearly) and the last two are merged
together.
So the only missing feature is you can't tell the difference between a
bug-fix release and a release that adds a new feature. Honestly this
isn't super important to me. I always do my dependencies in the form
"~0.2.3" and npm will match >= 0.2.3 and < 0.3.0. I depend on
bugfixes and features present in 0.2.3 and am ok with getting any new
features or bug fixes as long as it doesn't break my app.
In the context of shared libraries this is a good thing. If feature
additions were the middle digit and the first digit was breaking
changes then people would either always match ~2.3 ignoring the last
digit or ~2.3.5 and be locked to a certain set of features. For
common libraries that are shared among several modules, this would
cause duplication.
By merging the feature addition digit with the bugfix digit the first
digit is freed for major changes which is also useful.
So the question is, which is more valuable? Being able to mark
architectural changes or being able to tell feature additions apart
from bug fixes. I think we all agree it's a good thing to be able to
get bug fixes automatically without pulling in API breaking changes.
But only two digits are required for that.
As far as node itself, I have no say in how it's numbered and I
understand it's system, so it's fine by me. As a linux user I'm used
to the platform using different numbering systems than libraries.
On Thu, Sep 20, 2012 at 1:37 PM, Karl Tiedt <kti...@gmail.com> wrote:
> By this formula, Node has been 1.0+ since day one and never broken
> backwards compatibility... Its understandable that young projects
> hover below 1.0 in order to get a more throughly designed API in place
> (and maybe fix/remove API kinks that were bad ideas at one point in
> time)... but some would say that 3+ years is kinda pushing that safety
> net for such a largely used project...
> Essentially anyone familiar with semver would be leery of using Node
> for a large scale application with the lack of guarantee in backwards
> compatibility (or they should be without better explanation of the
> "Node way" of doing things).
> -Karl Tiedt
> On Thu, Sep 20, 2012 at 1:24 PM, Tim Caswell <t...@creationix.com> wrote:
>> To convert
>> node-community-style semver numbers to "official" semver numbers, use
>> this table.
>> 0.0.x -> 0.0.x
>> x.y.z -> (x + 1).y.z
>> So 0.3.14 would be 1.3.14 and 0.0.14 would stay 0.0.14.
The problem is packages don't use this consistently, and don't even make an effort to tell us of breaking changes. 0.x.x is supposed to mean, and often does mean, the package is in a period of rapid API breakage. But many packages simply use it as an excuse to break their API whenever they want. Node.js itself, Jade, Mongolian have all introduced more than one breaking change *as a bugfix, patch release increment.* There's absolutely no way to future-proof these dependencies, except to regularly check for updates, and either blacklist the breaking patch numbers as they're released, or upgrade your application accordingly. This is a waste of time and effort that could easily be avoided.
Also if you're releasing versions with a 0. prefix then what's the point? You're dropping the indication of new feature releases, just so you can have a leading 0.? This inconsistency is confusing and unnecessary.
On Thu, Sep 20, 2012 at 2:59 PM, Austin William Wright <
diamondma...@users.sourceforge.net> wrote:
> Also if you're releasing versions with a 0. prefix then what's the point?
> You're dropping the indication of new feature releases, just so you can
> have a leading 0.? This inconsistency is confusing and unnecessary.
You can easily use 0.x.y where x = new features/breaking changes and y =
bug fixes. The reason for using 0.x is to indicate that you have not
decided that the API is what you definitely want. While x and y in 0.x.y
have no meaning in semver, they can and often do have meaning in the real
world.
Whether people take this too far is a separate question. But at this point
you're arguing in black and white and that's just not how the ecosystem
actually works.
The API *does not need to be *what you definitely want. If you decide to later change the API, just release 2.0.0. The important part is that you tell us clearly that the API broke. That's all that matters.
On Thursday, September 20, 2012 12:04:10 PM UTC-7, Scott González wrote:
> On Thu, Sep 20, 2012 at 2:59 PM, Austin William Wright <
> diamon...@users.sourceforge.net <javascript:>> wrote:
>> Also if you're releasing versions with a 0. prefix then what's the point? >> You're dropping the indication of new feature releases, just so you can >> have a leading 0.? This inconsistency is confusing and unnecessary.
> You can easily use 0.x.y where x = new features/breaking changes and y = > bug fixes. The reason for using 0.x is to indicate that you have not > decided that the API is what you definitely want. While x and y in 0.x.y > have no meaning in semver, they can and often do have meaning in the real > world.
> Whether people take this too far is a separate question. But at this point > you're arguing in black and white and that's just not how the ecosystem > actually works.
On Thu, Sep 20, 2012 at 3:10 PM, Austin William Wright <
diamondma...@users.sourceforge.net> wrote:
> The API *does not need to be *what you definitely want. If you decide to
> later change the API, just release 2.0.0. The important part is that you
> tell us clearly that the API broke. That's all that matters.
What is the end game? Were you hoping to get everyone to smarten up, see
the error of their ways and change all of their package.json files?
Certainly making a distinction between an architectural change/rewrite is important for many reasons. But I don't think it's a distinction we need to split out in the version number. Developers are more inclined to be able to use out-of-bound information than the program, for example, we understand "The code rewrite happened in version 4, and again in 5." To the application that's depending on the library, it doesn't care. All it cares is that it's not compatible with anything past 2.
I'd also argue it teaches people that, since 0.4.0 can potentially mean a breaking change, so could 1.1.0 (even though it doesn't). I don't want to give this impression.
Perhaps ideally we would use four segments, "rewrite.major.minor.patch".
On Thursday, September 20, 2012 11:52:31 AM UTC-7, Tim Caswell wrote:
> For what it's worth, I see the value in using all three numbers to > their fullest potential as the spec describes.
> Also I explained my usage of node-style semver incorrectly and I > apologize.
> My personal standard is I bump the last digit for both bug fixes and > feature additions. Basically any change that won't break any code > that depends on my library. I bump the middle number when I make a > breaking change. So basically it's like the official semver except > the first digit is 0 forever (nearly) and the last two are merged > together.
> So the only missing feature is you can't tell the difference between a > bug-fix release and a release that adds a new feature. Honestly this > isn't super important to me. I always do my dependencies in the form > "~0.2.3" and npm will match >= 0.2.3 and < 0.3.0. I depend on > bugfixes and features present in 0.2.3 and am ok with getting any new > features or bug fixes as long as it doesn't break my app.
> In the context of shared libraries this is a good thing. If feature > additions were the middle digit and the first digit was breaking > changes then people would either always match ~2.3 ignoring the last > digit or ~2.3.5 and be locked to a certain set of features. For > common libraries that are shared among several modules, this would > cause duplication.
> By merging the feature addition digit with the bugfix digit the first > digit is freed for major changes which is also useful.
> So the question is, which is more valuable? Being able to mark > architectural changes or being able to tell feature additions apart > from bug fixes. I think we all agree it's a good thing to be able to > get bug fixes automatically without pulling in API breaking changes. > But only two digits are required for that.
> As far as node itself, I have no say in how it's numbered and I > understand it's system, so it's fine by me. As a linux user I'm used > to the platform using different numbering systems than libraries.
> On Thu, Sep 20, 2012 at 1:37 PM, Karl Tiedt <kti...@gmail.com<javascript:>> > wrote: > > By this formula, Node has been 1.0+ since day one and never broken > > backwards compatibility... Its understandable that young projects > > hover below 1.0 in order to get a more throughly designed API in place > > (and maybe fix/remove API kinks that were bad ideas at one point in > > time)... but some would say that 3+ years is kinda pushing that safety > > net for such a largely used project...
> > Essentially anyone familiar with semver would be leery of using Node > > for a large scale application with the lack of guarantee in backwards > > compatibility (or they should be without better explanation of the > > "Node way" of doing things).
> > -Karl Tiedt
> > On Thu, Sep 20, 2012 at 1:24 PM, Tim Caswell <t...@creationix.com<javascript:>> > wrote:
> >> To convert > >> node-community-style semver numbers to "official" semver numbers, use > >> this table.
> >> 0.0.x -> 0.0.x > >> x.y.z -> (x + 1).y.z
> >> So 0.3.14 would be 1.3.14 and 0.0.14 would stay 0.0.14.
If more than a dozen people are using your package, then next time you make a breaking change, release 1.0.0. Continue to clearly identify when you make breaking changes, when you release new features, and when you release a patch.
That'd help tremendously with the package ecosystem, I believe. Certainly it'd help me.
On Thursday, September 20, 2012 12:16:07 PM UTC-7, Rick Waldron wrote:
> On Thu, Sep 20, 2012 at 3:10 PM, Austin William Wright < > diamon...@users.sourceforge.net <javascript:>> wrote:
>> The API *does not need to be *what you definitely want. If you decide to >> later change the API, just release 2.0.0. The important part is that you >> tell us clearly that the API broke. That's all that matters.
> What is the end game? Were you hoping to get everyone to smarten up, see > the error of their ways and change all of their package.json files?
On Thu, Sep 20, 2012 at 2:25 PM, Austin William Wright
<diamondma...@users.sourceforge.net> wrote:
> If more than a dozen people are using your package, then next time you make
> a breaking change, release 1.0.0. Continue to clearly identify when you make
> breaking changes, when you release new features, and when you release a
> patch.
> That'd help tremendously with the package ecosystem, I believe. Certainly
> it'd help me.
Ok, so lets break this into two requests.
1. When releasing a version of a library, please clearly mark API
breaking changes so consumers of the library won't get bitten.
2. Migrate from
architecture-change.breaking-change.non-breaking-change numbers to
breaking-change.non-breaking-feature-addition.bug-fix numbers.
I think we all agree that 1. is a good idea. Authors who don't do
this cause trouble, yes, but it's not node's or npm's responsibility
to police this. Contact the authors directly or have a mailing list
thread directly about this issue.
Item 2 has varied opinions on it and there is a lot of momentum in the
"old" system. If I as an author suddenly release 1.0.0 as a way to
migrate to the "new" system it will send the wrong message to my
users. In current de-facto semantics that means API feature freeze
and the project is stable. I'm not saying it's right or wrong, just
saying that migrating is a lot of effort with little gain. If you
feel the gain is worth the effort, then address that directly, but
don't confuse it with item 1.
> On Thursday, September 20, 2012 12:16:07 PM UTC-7, Rick Waldron wrote:
>> On Thu, Sep 20, 2012 at 3:10 PM, Austin William Wright
>> <diamon...@users.sourceforge.net> wrote:
>>> The API does not need to be what you definitely want. If you decide to
>>> later change the API, just release 2.0.0. The important part is that you
>>> tell us clearly that the API broke. That's all that matters.
>> What is the end game? Were you hoping to get everyone to smarten up, see
>> the error of their ways and change all of their package.json files?
Personally, I avoid "~a" or even "~a.b.c" wherever possible. If my
architecture is working with pack...@a.b.c, then I want it to continue
working with pack...@a.b.c until I explicitly attempt an upgrade to version
"a.b.x", "a.x.y", etc.
You're complaining about shifting package versions breaking your
application, but *you're the one who told npm to shift versions at will*.
That said, you have control at the per-dependency level. Certain projects
and packages use the npm-enforced "semver" numbers in different ways, and
once you understand how Dependency X treats "minor" version changes, you
can be looser with approximately-versioned dependencies.
Is that so crazy?
Schoon
P.S. This assumes another practice all package authors should follow:
upping your version number every time you publish. The only reason not to
do this should be a Damn Good Reason(tm).
> 2. Migrate from architecture-change.breaking-change.non-breaking-change
numbers to breaking-change.non-breaking-feature-addition.bug-fix numbers.
I realized, I haven't seen this scheme before today, at least not as you explain. It *seems* to explain why people are hesitant to release a version 1.0.0, but when I've contacted authors about breaking changes they've released, by far the most common response I've gotten is e.g. "But I'm using major version zero, so it doesn't matter." This is what I am trying to respond to.
I'm a bit hesitant to single out individual packages or authors, though I guess I've already named a few: Node.js, Jade, Mongolian. I have no shortage of good things to say about the quality of the source code of all three of these packages, it's just that I've had repeated issues trying to figure out what broke what and when.
Other software doesn't seem to have such a problem. I've been using lots of internal Drupal API functions, and maybe while it's painful to code for, the only time the functionality actually broke on me was during an upgrade was the transition from 6 to 7 (as I expected). Express is on major version 3, and as expected, my ~2-depending application has always cleanly updated to another ~2 version, but doesn't upgrade to ~3. I like this. Unfortunately I can't name too many other packages that broke reverse compatibility, and unambiguously indicated when they did so.
If you're going to use the minor version number to indicate breakage, at least tell me that in the documentation, don't leave me guessing! But still, why make an exception to the standard, which is to use the major number? It doesn't accomplish anything except to add confusion and inconsistency.
If you suddenly release 1.0.0, this indicates a major change. This can include a change in numbering scheme. This is exactly what the Linux kernel did. 3 is reverse compatible with 2.6, the only incompatibility is in the numbering scheme. I really liked the outcome of this change.
On Thursday, September 20, 2012 12:54:40 PM UTC-7, Tim Caswell wrote:
> On Thu, Sep 20, 2012 at 2:25 PM, Austin William Wright > <diamon...@users.sourceforge.net <javascript:>> wrote: > > If more than a dozen people are using your package, then next time you > make > > a breaking change, release 1.0.0. Continue to clearly identify when you > make > > breaking changes, when you release new features, and when you release a > > patch.
> > That'd help tremendously with the package ecosystem, I believe. > Certainly > > it'd help me.
> Ok, so lets break this into two requests.
> 1. When releasing a version of a library, please clearly mark API > breaking changes so consumers of the library won't get bitten.
> 2. Migrate from > architecture-change.breaking-change.non-breaking-change numbers to > breaking-change.non-breaking-feature-addition.bug-fix numbers.
> I think we all agree that 1. is a good idea. Authors who don't do > this cause trouble, yes, but it's not node's or npm's responsibility > to police this. Contact the authors directly or have a mailing list > thread directly about this issue.
> Item 2 has varied opinions on it and there is a lot of momentum in the > "old" system. If I as an author suddenly release 1.0.0 as a way to > migrate to the "new" system it will send the wrong message to my > users. In current de-facto semantics that means API feature freeze > and the project is stable. I'm not saying it's right or wrong, just > saying that migrating is a lot of effort with little gain. If you > feel the gain is worth the effort, then address that directly, but > don't confuse it with item 1.
> > On Thursday, September 20, 2012 12:16:07 PM UTC-7, Rick Waldron wrote:
> >> On Thu, Sep 20, 2012 at 3:10 PM, Austin William Wright > >> <diamon...@users.sourceforge.net> wrote:
> >>> The API does not need to be what you definitely want. If you decide to > >>> later change the API, just release 2.0.0. The important part is that > you > >>> tell us clearly that the API broke. That's all that matters.
> >> What is the end game? Were you hoping to get everyone to smarten up, > see > >> the error of their ways and change all of their package.json files?
Actually, I don't tag my dependencies like that either, I use Git submodules, so I know exactly, byte-for-byte what code I'm distributing.
This doesn't eliminate the need for upgrading packages from time to time. I need to be able to run an "git node update" command and have 20 packages update, without having to manually sift through every one and test if it upgrades well or not.
On Thursday, September 20, 2012 1:42:22 PM UTC-7, Michael Schoonmaker wrote:
> Personally, I avoid "~a" or even "~a.b.c" wherever possible. If my > architecture is working with pack...@a.b.c, then I want it to continue > working with pack...@a.b.c until I explicitly attempt an upgrade to version > "a.b.x", "a.x.y", etc.
> You're complaining about shifting package versions breaking your > application, but *you're the one who told npm to shift versions at will*.
> That said, you have control at the per-dependency level. Certain projects > and packages use the npm-enforced "semver" numbers in different ways, and > once you understand how Dependency X treats "minor" version changes, you > can be looser with approximately-versioned dependencies.
> Is that so crazy?
> Schoon
> P.S. This assumes another practice all package authors should follow: > upping your version number every time you publish. The only reason not to > do this should be a Damn Good Reason(tm).
