> 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?
> >> This is a serious question.
> > --
> > 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<javascript:>
> > To unsubscribe from this group, send email to
> > nodejs+un...@googlegroups.com <javascript:>
> > For more options, visit this group at
> > http://groups.google.com/group/nodejs?hl=en?hl=en
