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.
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.
On Thursday, September 20, 2012 1:52:36 PM UTC-7, Michael Schoonmaker wrote:
> 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.
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.
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.
Il giorno 21/set/2012, alle ore 09:17, Michael Schoonmaker ha scritto:
> 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:
> Understand how my dependencies define versions.
> Lock versions down for production.
> Upgrade explicitly and with cause.
> Update my package.json accordingly.
> Schoon
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.
On Thursday, September 20, 2012 4:17:51 PM UTC-7, Michael Schoonmaker wrote:
> 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.
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).
On Thursday, September 20, 2012 4:51:40 PM UTC-7, Chris Corbyn wrote:
> 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.
> Il giorno 21/set/2012, alle ore 09:17, Michael Schoonmaker ha scritto:
> 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.
> 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.
On Thu, Sep 20, 2012 at 5:00 PM, Austin William Wright <
diamondma...@users.sourceforge.net> wrote:
> 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).
> On Thursday, September 20, 2012 4:51:40 PM UTC-7, Chris Corbyn wrote:
>> 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.
>> Il giorno 21/set/2012, alle ore 09:17, Michael Schoonmaker ha scritto:
>> 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<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.
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.
On Thursday, September 20, 2012 5:26:10 PM UTC-7, Mark Hahn wrote:
> > 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.
> On Thu, Sep 20, 2012 at 5:00 PM, Austin William Wright < > diamon...@users.sourceforge.net <javascript:>> wrote:
>> 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).
>> On Thursday, September 20, 2012 4:51:40 PM UTC-7, Chris Corbyn wrote:
>>> 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.
>>> Il giorno 21/set/2012, alle ore 09:17, Michael Schoonmaker ha scritto:
>>> 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<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.
> 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.
On Thu, Sep 20, 2012 at 5:38 PM, Austin William Wright <
diamondma...@users.sourceforge.net> wrote:
> 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.
> On Thursday, September 20, 2012 5:26:10 PM UTC-7, Mark Hahn wrote:
>> > 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.
>> On Thu, Sep 20, 2012 at 5:00 PM, Austin William Wright <diamon...@users.*
>> *sourceforge.net> wrote:
>>> 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).
>>> On Thursday, September 20, 2012 4:51:40 PM UTC-7, Chris Corbyn wrote:
>>>> 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.
>>>> Il giorno 21/set/2012, alle ore 09:17, Michael Schoonmaker ha scritto:
>>>> 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.**htm**l#version<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.
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.
On Thursday, September 20, 2012 5:45:03 PM UTC-7, Mark Hahn wrote:
> > 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.
> On Thu, Sep 20, 2012 at 5:38 PM, Austin William Wright < > diamon...@users.sourceforge.net <javascript:>> wrote:
>> 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.
>> On Thursday, September 20, 2012 5:26:10 PM UTC-7, Mark Hahn wrote:
>>> > 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.
>>> On Thu, Sep 20, 2012 at 5:00 PM, Austin William Wright <diamon...@users. >>> **sourceforge.net> wrote:
>>>> 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).
>>>> On Thursday, September 20, 2012 4:51:40 PM UTC-7, Chris Corbyn wrote:
>>>>> 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.
>>>>> Il giorno 21/set/2012, alle ore 09:17, Michael Schoonmaker ha scritto:
>>>>> 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.**htm**l#version<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.
> On Thu, Sep 20, 2012 at 2:27 PM, Austin William Wright
> <diamondma...@users.sourceforge.net
> <mailto: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.
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."
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.
On Thu, Sep 20, 2012 at 6:51 PM, Alan Gutierrez <a...@prettyrobots.com> wrote:
> On 9/20/12 2:30 PM, Scott González wrote:
>> On Thu, Sep 20, 2012 at 2:27 PM, Austin William Wright
>> <diamondma...@users.sourceforge.net
>> <mailto: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.
> 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."
> 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.
> 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?
