Keeping semantics in your version numbers, i.e. please don't release major version zero

[Austin William Wright]

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.

[Mark Hahn]

> 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?

--
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 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

[Austin William Wright]

It's kind of required if you're releasing a package using npm: https://npmjs.org/doc/json.html

[Mariusz Nowak]

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.

[Rick Waldron]

On Sep 20, 2012 3:52 AM, "Mariusz Nowak" <mar...@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

[Mark Hahn]

> It's kind of required

By whom?  

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.

[Austin William Wright]

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.

[Mark Hahn]

> 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.

--

[Tim Caswell]

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.

[Austin William Wright]

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.

[Scott González]

On Thu, Sep 20, 2012 at 2:27 PM, Austin William Wright <diamon...@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.

[Austin William Wright]

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.

[Karl Tiedt]

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

[Austin William Wright]

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.

[Tim Caswell]

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.

[Austin William Wright]

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.

[Scott González]

On Thu, Sep 20, 2012 at 2:59 PM, Austin William Wright <diamon...@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.

[Austin William Wright]

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.

[Rick Waldron]

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?

This is a serious question.

[Austin William Wright]

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".

[Austin William Wright]

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.

[Tim Caswell]

On Thu, Sep 20, 2012 at 2:25 PM, Austin William Wright
<diamon...@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?
>>
>> This is a serious question.
>>
>>

[Michael Schoonmaker]

Personally, I avoid "~a" or even "~a.b.c" wherever possible. If my architecture is working with pac...@a.b.c, then I want it to continue working with pac...@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).

[Austin William Wright]

> 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.

[Austin William Wright]

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.

[Michael Schoonmaker]

I think one way we disagree is in the definition of "standard". All npm guarantees is that the version by parseable by node-semver, not that they follow the complete semver specification.

It may not be a documented "standard", but what Tim alludes to, architecture-change.breaking-change.non-breaking-change, is a common practice.

Schoon

[Austin William Wright]

I guess that's what I'm advocating against: Using some scheme without any documentation of it makes your program unpredictable. And not just runtime unpredictable (at least we can always refer to the ultimate documentation, the source code), but we don't know how well it will upgrade in the future. That's arguably even worse. There's no excuse for having to guess which version number means what, especially when it, in all other respects, appears to conform to an existing, already used standard.

[Michael Schoonmaker]

I don't disagree with you insofar as using something that looks like semver without being semver can be confusing.

However, what I do disagree with is the attitude that we should change common practice because there is a similar-looking standard. Does that make sense? It's one thing to be confusing. It's something else entirely that the ship has sailed, and there are plenty of people on the deck having a great time.

I'm relatively new to Node (on the order of almost a year instead of several), but I understand what npm version numbers entail, and I understand that it's my package.json that describes what version of each dependency I use. Just as two applications may use different versioning schemes altogether, so two package developers may interpret https://npmjs.org/doc/json.html#version differently. Therefore, it's my responsibility to:

1. Understand how my dependencies define versions.
2. Lock versions down for production.
3. Upgrade explicitly and with cause.
4. Update my package.json accordingly.

Schoon

[Chris Corbyn]

I'll apply my same thinking under Rails/rubygems/bundler to node/npm. I don't ever look at version numbers of gems I use, or NPM modules now that I've started doing some node too. I install them, version control them and write tests. If my app works with the dependencies at the versions I installed, I don't need to care if the gem/npm module developer then starts hacking and making breaking changes in the main repo. My versions are frozen, until I decide to try updating them. When I update my dependencies, I run my tests. If the tests explode, I have two choices: 1. figure out what I need to change to get back up and running, or 2. lock the dependency to a version I know happens to work.

I do tend to look at how responsive the developer is to issues/pull requests and how long it's been since the last commit, but that's more because I don't want to use an abandoned project.

I don't really see how ongoing development of a dependency in your application is likely to cause any issues, provided you actually freeze versions. In Rails Gemfile.lock ensures new developer joining the team have all the same versions. In Node, installing the modules locally works fine too. And make sure you have good test coverage.

[Austin William Wright]

Semver used by most all the packages that I depend on. The problem is that (1) most of these dependencies are on ~0 and feel free to break their API any time without warning (this is what they tell me), and (2) those that don't use semver, don't disclose any scheme at all. It is not documented, it is unpredictable, and not future-proof. This is the problem, this wastes developer time, and is hardly a practice that should be continued, even if it was costly to change mid-course.

Locking down your versions is a good idea, but not a solution to this problem. As mentioned, I use Git submodules (you can't get much more locked-down than that). Updating twenty packages should take on the order of a minute, not half a day.

[Austin William Wright]

For production applications, having tests and maintaining dependencies is a good idea.  However I explained this isn't a replacement for the major version number:

(1) Not everyone is writing production applications. My own ~0 application in production moves too fast for tests to be meaningful.

(2) You should not require people to use trial and error to figure out which release is compatible when updating dependencies, developers should be able to identify at a glance which version is breaking, and which is not, so we know which version to update to (I use Git submodules for this task).

[Mark Hahn]

> developers should be able to identify at a glance which version is breaking, and which is not

You sure have a lot of faith in the developers.  I would never trust any version numbering scheme.  When I need a new feature or a bug-fix I test the latest version.  I don't even pay attention to version numbers.  I can't imagine making any of my decisions based on version numbers.

[Austin William Wright]

I never said you need to trust the library developer, but that's no excuse for them to mis-identify which versions are breaking, and which are stable.

You want to update to the latest package that's compatible with your current version. What's the easiest way to do that? I should not need to trial-and-error releases to find a good, working one.

[Mark Hahn]

> You want to update to the latest package that's compatible with your current version. 

I don't understand why you would want to do that.  You are taking a risk for no reason.  

I only update when I need a feature or some bug is discovered.  In either case I may need to change my code or may not.  I don't really have any control over that.

I said I was going to shut up and I didn't.  I will try harder now.

[Austin William Wright]

Well then you have no need for version numbers at all, what are you complaining about?

Some of us, however, do rely on upgrading packages. Some of use multiple packages that require() the same module, we need a way to resolve which package is mutually compatible. You can't make broad assumptions like "never upgrade packages". That doesn't solve the fundamental problem.

[Alan Gutierrez]

On 9/20/12 2:30 PM, Scott Gonz�lez wrote:
> On Thu, Sep 20, 2012 at 2:27 PM, Austin William Wright
> <diamon...@users.sourceforge.net

> <mailto:diamon...@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.

While I'm developing a library, I use 0.0.x as pre-release, where API
breaking updates occur at every revision. From Timezone:

"On the 0.0.x branch, API changes may break applications. Please use an
absolute version number in your package.json to hold onto a version
Timezone that works for you. When 0.0.x development is done, I'll create
an 0.2.0 branch for application use and a 0.1.0 for any further
development. The 0.2.0 branch will be an API freeze."

https://github.com/bigeasy/timezone/issues/41

So, like Scott says, but with no tilde. Each upgrade requires your
attention.

Thus, I'm not following the semvar document, but I'm adhering to the
notion that semvar helps you manage API instabilities, documenting my
reasoning.

0.0.x is pre-release for the intrepid.

--
Alan Gutierrez - http://github.com/bigeasy - http://twitter.com/bigeasy

[Isaac Schlueter]

So, there are two topics here that are both very interesting, in my opinion.

1. When publishing an app, you should freeze your dependencies to
something that you know works. In varying degrees of frozenness, that
can be done via: a) checking node_modules into git, b) using npm
shrinkwrap, c) depending on explicit version numbers rather than
ranges.

However, when publishing a library or utility that depends on other
utilities and libraries, depending on explicit version numbers is
rather obnoxious. It makes it harder than necessary to take in
bug-fixes. Some packages are updated quite frequently to add minor
things in very safe ways that do not affect the api.

For example, the `mime` package gets a new version bump for each
mime-type that is added. If your library depends on the api, but it
is unlikely that a new mime type will break your library, then fixing
the patch version is annoying. Now, if I want to use your library,
and I need support for a mime-type that was added after you published,
I have to manually edit your package.json to loosen the constraint,
send you a pull request, wait for you to push an update, and then pull
in your update later maybe. It adds ceremony and complexity. Your
app isn't "about" mime-types, so having to push updates to support new
mime types is not the correct separation of concerns.

Dependency fixing should be done at the highest app level, not at the
library/util level. Library modules should be as broad as is
"reasonable", and the value of "reasonable" is dependent on context
(see below.)

This has been our experience so far, and I haven't yet seen any
significant exceptions to that rule.


2. There are open questions about exactly what semantics we're meaning
to communicate with our semantic versions.

At the rudimentary level, package versions must be parseable by the
node semver package. In other words, npm package versions must be
version numbers complying with the npm package version scheme,
parseable by the npm package version parser. (The first rule of
taugology club is the first rule of tautology club...) There are some
ideas about what *should* be communicated with our semantic versions.
One interesting model is that proposed by semver.org, but it's clearly
not the only thing that can be implied.

npm itself gives you the tools to communicate using version numbers,
but it does not stipulate what that communication must be, except to
specify the ordering of version numbers, and some special syntax for
specifying ranges of acceptable versions. That's it.

For some authors, 0.x means "I am going to break this thing, don't
rely on it." For others, 0.0.x means that, but 0.1.x means "You can
rely on this, at least up to 0.2.x", and for others, it means "You can
rely on this, at least up to 1.x." In node-core, 0.x means "unstable"
if x%2, and I don't know of any npm package that uses that pattern.

Ultimately, using someone else's code is a bond of trust between you
and them. You need to learn their mind a little bit. You need to
read their docs, run their tests, and probably will end up fixing some
of their bugs. Part of this process is accepting that their
versioning scheme might not be 100% the same as yours, or that they
might make a mistake (gosh!) and publish a change that violates their
own versioning pattern in some unexpected way.

Part of the problem here is that we're not the borg, and we don't all
think the same. When faced with semantic ambiguities, some nerds
think, "I know, I'll use a specification!" I'd tell you how many
problems you'd now have, but the specification for how to count
problems is ambiguous.

In this case, I think it's best to just admit that what's best for one
package might not be best for another. Evaluating dependencies is
part of the craft of making software. You can't solve this problem
with math. (Or at least, trying to solve it with math thus far has
been unsuccessful, and is probably more work than just using your
human brain to figure out which version to use, or what range is
acceptable.)

For what it's worth, here's the scheme I use in my packages:

1. If there's a major architecture/semantic change in program
behavior, almost certain to break programs using it today, then bump
the major version. (Ie, npm 0.x to npm 1.x.)
2. If there's a potentially breaking api change, which is likely to be
safe for most users, and doesn't change the nature of the program too
considerably, then bump the minor version.
3. Any other change, bugfix, etc., bump the patch version.

Other perfectly valid schemes:

1. Bump the major when any breaking API change is made.
2. Bump the minor when any API change at all is made.
3. Bump the patch when any API-compatible change is made.

1. Bump the major when there is an API change.
2. Bump the minor when a bug is fixed that touches any underlying code.
3. Bump the patch when a new data record is added. (Ie, in the mime
case above.)

1. Bump the major from 0 to 1 when it's considered feature complete,
and again for major re-architectures.
2. Bump the minor from 0 to 1 when it's passing tests, and again for
any API changes.
3. Bump the patch for API additions prior to 0.1.x, and for bugfixes after.
4. Bump the build for bugfixes prior to 0.1.x, and never again afterwards.

The possibilities are endless.

Culturally, node is the sort of place where those in power try to
dictate as little as necessary. Semantics are something that come out
of communication, not something that ought to be injected into it.

What I've observed in practice, and what we've made the default for
the `--save` behavior in npm, is that people tend to be a bit
suspicious of 0.0.x packages -- if it works, great, but I don't trust
that 0.0.x+1 will still work -- and are a bit more trusting of
versions >=0.1.0. So, when you do `--save` or `--save-dev` in npm,
it'll put the ~ in front of versions that don't start with 0.0.


The point of Austin's OP, which some have echoed in this thread,
seemed to be: "Starting with a 0 is not a license to publish bugs." I
agree with him, but in the other direction ;) You don't need a
license to publish bugs. Just change the version number, and it's a
different thing, go crazy. Publish all the bugs you want.

However, recognize that your credibility suffers, and that the bond
between author and user is a bond of trust, so taking it lightly will
lead to you losing face in the hearts and minds of your peers.
Reputations are long-lived, and can have social and financial
consequences long into the future. So, it's in your best interest to
try to be responsible, and do your best to communicate where a project
is in its development. If 0.x means "This is going to break
repeatedly", well, ok... you should probably also mention that in the
readme. There's certainly nothing wrong with experimentation, but
people tend to get upset when they're surprised.

[xmilliard]

+1