New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

1.0.0 is not just a number #2

Open
domenic opened this Issue Feb 21, 2013 · 35 comments

Comments

Projects
None yet
9 participants
@domenic

domenic commented Feb 21, 2013

From the semver spec:

Major version zero (0.y.z) is for initial development. Anything may change at any time. The public API should not be considered stable.

Before 1.0.0, the version numbers have no semantics. A patch version could introduce backward-incompatible changes. Indeed, subsequent parts of the spec explicitly state they only apply if the major version number x is > 0.

@dominictarr

This comment has been minimized.

Show comment
Hide comment
@dominictarr

dominictarr Feb 21, 2013

Owner

Technically, you are correct.

However, our goal here is just to explain the minimum to get npm authors not breaking other people's modules,
by say, putting a breaking change into a minor version.

We don't mention the bit where versions under 1.0.0 have a special meaning, because npm doesn't handle them specially, and because we want to encourage publishing as early as possible.

I think the reason the semver spec is like that is because it fits with the way that people have traditionally used versions,
so that they can easily 'port to semver'. This is not the best part of the semver spec.

We could consider this "npm flavored semver"

Owner

dominictarr commented Feb 21, 2013

Technically, you are correct.

However, our goal here is just to explain the minimum to get npm authors not breaking other people's modules,
by say, putting a breaking change into a minor version.

We don't mention the bit where versions under 1.0.0 have a special meaning, because npm doesn't handle them specially, and because we want to encourage publishing as early as possible.

I think the reason the semver spec is like that is because it fits with the way that people have traditionally used versions,
so that they can easily 'port to semver'. This is not the best part of the semver spec.

We could consider this "npm flavored semver"

@domenic

This comment has been minimized.

Show comment
Hide comment
@domenic

domenic Feb 21, 2013

I don't think that's quite the right way of looking at it.

npm doesn't handle any version numbers specially. It's entirely up to package consumers and maintainers to give semantics to their versions, and enforce them.

Thus myself, as an Orthodox Semverist, will often make breaking changes from 0.0.1 to 0.0.2, and if I depend on any package with a version number < 1.0.0, I will pin it exactly to e.g. =0.1.2, since I know that the switch from 0.1.2 to 0.1.3 could break anything and everything.

On the other hand, the Reformed Semverists (what you explain in this repo) might say that the idea of publishing code before you lock down a public API is stupid, and so there is no need for special semantics for that case, and thus we should start at 0.0.0 instead of reserving a version range for people who make rapid changes. Those people will not make breaking changes from 0.0.1 to 0.0.2, and will pin versions at ~0.1 without worry, since they assume nobody will break things without bumping the major version, even if the major version is 0.

Finally, we have the Iconoclast Semverists. They seem believe that below 1.0.0, the minor version increments when there are breaking changes, and the patch version increments when there are new features. Thus they will pin versions at ~0.1.2, but not at ~0.1, since they think the switch from 0.1.2 to 0.2.0 could break backward compatibility, whereas 0.1.2 to 0.1.3 won't.

In my experience we have a lot of Iconoclast Semverists in the community. We have very few Orthodox Semverists, and before this repo, I'd never heard the Reformed Semverist point of view that you seem to be espousing.

Regardless, npm does not pick out any of these approaches as more or less correct. It's entirely up to the way that package consumers pin their versions using npm, and package producers publish using npm. So your Reformed Semverist approach doesn't really seem to be "npm flavored semver" as much as "don't publish code before locking down your public API-flavored semver."

domenic commented Feb 21, 2013

I don't think that's quite the right way of looking at it.

npm doesn't handle any version numbers specially. It's entirely up to package consumers and maintainers to give semantics to their versions, and enforce them.

Thus myself, as an Orthodox Semverist, will often make breaking changes from 0.0.1 to 0.0.2, and if I depend on any package with a version number < 1.0.0, I will pin it exactly to e.g. =0.1.2, since I know that the switch from 0.1.2 to 0.1.3 could break anything and everything.

On the other hand, the Reformed Semverists (what you explain in this repo) might say that the idea of publishing code before you lock down a public API is stupid, and so there is no need for special semantics for that case, and thus we should start at 0.0.0 instead of reserving a version range for people who make rapid changes. Those people will not make breaking changes from 0.0.1 to 0.0.2, and will pin versions at ~0.1 without worry, since they assume nobody will break things without bumping the major version, even if the major version is 0.

Finally, we have the Iconoclast Semverists. They seem believe that below 1.0.0, the minor version increments when there are breaking changes, and the patch version increments when there are new features. Thus they will pin versions at ~0.1.2, but not at ~0.1, since they think the switch from 0.1.2 to 0.2.0 could break backward compatibility, whereas 0.1.2 to 0.1.3 won't.

In my experience we have a lot of Iconoclast Semverists in the community. We have very few Orthodox Semverists, and before this repo, I'd never heard the Reformed Semverist point of view that you seem to be espousing.

Regardless, npm does not pick out any of these approaches as more or less correct. It's entirely up to the way that package consumers pin their versions using npm, and package producers publish using npm. So your Reformed Semverist approach doesn't really seem to be "npm flavored semver" as much as "don't publish code before locking down your public API-flavored semver."

@suarasaur

This comment has been minimized.

Show comment
Hide comment
@suarasaur

suarasaur Feb 21, 2013

guys, let's not be so strict about all of this. there's an easy way to tell a module's awesome level: https://npmjs.org/package/powerlevel

suarasaur commented Feb 21, 2013

guys, let's not be so strict about all of this. there's an easy way to tell a module's awesome level: https://npmjs.org/package/powerlevel

@dominictarr

This comment has been minimized.

Show comment
Hide comment
@dominictarr

dominictarr Feb 21, 2013

Owner

@domenic there is also at least one developer I know who NEVER uses ~, and pins everything to an exact version. A Paranoid Semverist?

So, although I like the idea of a Reformed Semverist, but I suggest that the true meaning of Reformed Serverism means that the core part of SemVer is the MAJOR.MINOR.PATCH, and that one may start publishing at 0.0.0,
and whenever you make a breaking change, you bump major version, even if it was just one small thing that broke.
Whether or not it was a total rewrite, that doesn't matter to the module's user.

If their module ends up as 5.6.13, then great, because they have stuck to the Sacred Semantics.

This is a great progress to some other versioning patterns, like in ubuntu distro, where the major version is just the year,
or oracle db - the first release was called oracle v2, because they didn't think anyone would be stupid enough buy an oracle v1...

Some people seem to attach some sentiment to versions, and think that the difference between 1.. and 2.. just means "a whole lot".

All Semverist Sects must reject Sentimental Versioning.

I guess Reformed Semverists could avoid this agrument explicitly by always starting at 1.0.0.

Owner

dominictarr commented Feb 21, 2013

@domenic there is also at least one developer I know who NEVER uses ~, and pins everything to an exact version. A Paranoid Semverist?

So, although I like the idea of a Reformed Semverist, but I suggest that the true meaning of Reformed Serverism means that the core part of SemVer is the MAJOR.MINOR.PATCH, and that one may start publishing at 0.0.0,
and whenever you make a breaking change, you bump major version, even if it was just one small thing that broke.
Whether or not it was a total rewrite, that doesn't matter to the module's user.

If their module ends up as 5.6.13, then great, because they have stuck to the Sacred Semantics.

This is a great progress to some other versioning patterns, like in ubuntu distro, where the major version is just the year,
or oracle db - the first release was called oracle v2, because they didn't think anyone would be stupid enough buy an oracle v1...

Some people seem to attach some sentiment to versions, and think that the difference between 1.. and 2.. just means "a whole lot".

All Semverist Sects must reject Sentimental Versioning.

I guess Reformed Semverists could avoid this agrument explicitly by always starting at 1.0.0.

@domenic

This comment has been minimized.

Show comment
Hide comment
@domenic

domenic Feb 21, 2013

Hah, yes, I think I know who you're talking about ;).

I understand the attraction of Reformed Semverist for its simplicity, which you do state well. However, (a) I don't know any packages that use that philosophy; (b) it's the same as Orthodox Semverist except it doesn't give you that 0.x.y window wherein you can publish things publicly while not attaching semantics to your versions.

The question, I guess, is whether that window is valuable, and more importantly, whether it should be explained in this guide. I'd say it is valuable, but it could be left as an "advanced feature" that doesn't need explanation.

domenic commented Feb 21, 2013

Hah, yes, I think I know who you're talking about ;).

I understand the attraction of Reformed Semverist for its simplicity, which you do state well. However, (a) I don't know any packages that use that philosophy; (b) it's the same as Orthodox Semverist except it doesn't give you that 0.x.y window wherein you can publish things publicly while not attaching semantics to your versions.

The question, I guess, is whether that window is valuable, and more importantly, whether it should be explained in this guide. I'd say it is valuable, but it could be left as an "advanced feature" that doesn't need explanation.

@dominictarr

This comment has been minimized.

Show comment
Hide comment
@dominictarr

dominictarr Feb 21, 2013

Owner

All my modules are Reformist Semver.

Hmm, writing small targeted modules, I either abandon them after I realize they wern't the right idea - probably not getting past a major version... or if it turned out to be the right idea, then I probably don't change it much.

I usually don't write a new module for the same thing with the same name, I create a new module, and abandon the old one, so I'm happy as a reformed semverist.

So, if we are to make this guide compatible with orthodox semverism, (while keeping it as simple as it is) we could recommend starting at 1.0.0, or always using exact versions under 1.0.0, so, use "module": "0.x.y" but it's okay to use "module": "~1.x.y" or "module": "~1.x"

Owner

dominictarr commented Feb 21, 2013

All my modules are Reformist Semver.

Hmm, writing small targeted modules, I either abandon them after I realize they wern't the right idea - probably not getting past a major version... or if it turned out to be the right idea, then I probably don't change it much.

I usually don't write a new module for the same thing with the same name, I create a new module, and abandon the old one, so I'm happy as a reformed semverist.

So, if we are to make this guide compatible with orthodox semverism, (while keeping it as simple as it is) we could recommend starting at 1.0.0, or always using exact versions under 1.0.0, so, use "module": "0.x.y" but it's okay to use "module": "~1.x.y" or "module": "~1.x"

@dominictarr

This comment has been minimized.

Show comment
Hide comment
@dominictarr

dominictarr Feb 21, 2013

Owner

I am reluctant, though, because explaining that makes the whole thing a lot more complicated.

Owner

dominictarr commented Feb 21, 2013

I am reluctant, though, because explaining that makes the whole thing a lot more complicated.

@domenic

This comment has been minimized.

Show comment
Hide comment
@domenic

domenic Feb 21, 2013

I think it could be left simple by changing the example, and replacing the two sentences about 1.0.0 with something like

"Your package should be 1.0.0 as soon as you are ready for other people to start depending on it. The period before 1.0.0 is for rapidly iterating your API, with no guarantees about the version semantics. This is helpful for code you just want to get out there, share, and collaborate on, but not so helpful for code you want others to build with."

domenic commented Feb 21, 2013

I think it could be left simple by changing the example, and replacing the two sentences about 1.0.0 with something like

"Your package should be 1.0.0 as soon as you are ready for other people to start depending on it. The period before 1.0.0 is for rapidly iterating your API, with no guarantees about the version semantics. This is helpful for code you just want to get out there, share, and collaborate on, but not so helpful for code you want others to build with."

@suarasaur

This comment has been minimized.

Show comment
Hide comment
@suarasaur

suarasaur Feb 21, 2013

I don't think it really adds that much cognitive overhead to explain that version numbers < 1 are "preview" releases. I think this encourages people to release earlier, as it acts as something of a safety net.

suarasaur commented Feb 21, 2013

I don't think it really adds that much cognitive overhead to explain that version numbers < 1 are "preview" releases. I think this encourages people to release earlier, as it acts as something of a safety net.

@dominictarr

This comment has been minimized.

Show comment
Hide comment
@dominictarr

dominictarr Feb 21, 2013

Owner

Right, so I could say "normally you should start at 1, unless your module is experimental"

However, I must say, I find the idea of semanticless versions appaling, and do not wish to encourage it.

That would just need all these "the api looks stable, please make it 1.0.0" issues.

Take https://npmjs.org/package/q for example, this look pretty stable to me, and very well documented.
Is q@0.9.0 gonna be a breaking change?

Owner

dominictarr commented Feb 21, 2013

Right, so I could say "normally you should start at 1, unless your module is experimental"

However, I must say, I find the idea of semanticless versions appaling, and do not wish to encourage it.

That would just need all these "the api looks stable, please make it 1.0.0" issues.

Take https://npmjs.org/package/q for example, this look pretty stable to me, and very well documented.
Is q@0.9.0 gonna be a breaking change?

@domenic

This comment has been minimized.

Show comment
Hide comment
@domenic

domenic Feb 21, 2013

@dominictarr yes it is; we will be removing several deprecated methods.

domenic commented Feb 21, 2013

@dominictarr yes it is; we will be removing several deprecated methods.

@dominictarr

This comment has been minimized.

Show comment
Hide comment
@dominictarr

dominictarr Feb 21, 2013

Owner

that is silly. make it 1.0.0

Owner

dominictarr commented Feb 21, 2013

that is silly. make it 1.0.0

@dominictarr

This comment has been minimized.

Show comment
Hide comment
@dominictarr

dominictarr Feb 28, 2013

Owner

oh, from http://semver.org FAQ

How do I know when to release 1.0.0?

If your software is being used in production, it should probably already be 1.0.0. If you have a stable API on which users have come to depend, you should be 1.0.0. If you're worrying a lot about backwards compatibility, you should probably already be 1.0.0.

Owner

dominictarr commented Feb 28, 2013

oh, from http://semver.org FAQ

How do I know when to release 1.0.0?

If your software is being used in production, it should probably already be 1.0.0. If you have a stable API on which users have come to depend, you should be 1.0.0. If you're worrying a lot about backwards compatibility, you should probably already be 1.0.0.

@suarasaur

This comment has been minimized.

Show comment
Hide comment
@suarasaur

suarasaur Feb 28, 2013

If your software is being used in production, it should probably already be 1.0.0.

That's a silly (and arbitrary) burden of stability for production software. It should be stable as in "not crash and burn", but there's no reason you can't have rapidly changing software in production without making claims of api stability.

Maybe if the major version number < 1 isn't well regarded, I should just be making more liberal (if less semantic) use of tags after the version number.

This post is version 1.0.1-experimental.

suarasaur commented Feb 28, 2013

If your software is being used in production, it should probably already be 1.0.0.

That's a silly (and arbitrary) burden of stability for production software. It should be stable as in "not crash and burn", but there's no reason you can't have rapidly changing software in production without making claims of api stability.

Maybe if the major version number < 1 isn't well regarded, I should just be making more liberal (if less semantic) use of tags after the version number.

This post is version 1.0.1-experimental.

@maxogden

This comment has been minimized.

Show comment
Hide comment
@maxogden

maxogden Feb 28, 2013

Collaborator

I think using semver as a marketing tool is silly so I just blindly increment numbers based on the 3 simple rules stated in semver-ftw. "marketing tool" meaning using 1.0.0 to convey some sort of reliability to potential users

Collaborator

maxogden commented Feb 28, 2013

I think using semver as a marketing tool is silly so I just blindly increment numbers based on the 3 simple rules stated in semver-ftw. "marketing tool" meaning using 1.0.0 to convey some sort of reliability to potential users

@defunctzombie

This comment has been minimized.

Show comment
Hide comment
@defunctzombie

defunctzombie Feb 28, 2013

🔥 death to non-believers 🔥

defunctzombie commented Feb 28, 2013

🔥 death to non-believers 🔥

@jugglinmike

This comment has been minimized.

Show comment
Hide comment
@jugglinmike

jugglinmike Mar 1, 2013

The goal of getting people to publish as early as possible is well-served by a "special" interpretation of pre-1.0.0 releases.

It's good for developers to get their ideas published as early as possible--it sounds like everyone agrees on the basic tenets of OSS behind this claim. There is a negative effect to this, though: module consumers have no way of determining API stability.

Adopting a module is a commitment on the part of the consumer, and I think it's fair to say they want two things:

  1. The module not to break their application
  2. The module to enjoy the continued support/improvements that minor and patch releases provide

For example: a 2-month-old module at version 23.0.0 is extremely unattractive to me. By committing to it, I can expect a lot of maintenance cost relative to patches that are inevitably required.

Of course, a module at 0.23.0 is no different. But at least with that version, I know what I'm getting in to. I can easily compare that module with one at 1.4.3 and determine which is more likely to work and receive support in its current form for some time. If I like 0.23.0's API and I'm just making some dumb Twitter bot, then I'll use that. But If I'm building something to hand off to a client, then I'll use 1.1.3 with reasonable expectation of support.

Without the semantic distinction of 1.0.0, I have no way of predicting the risk I take committing to a given module.

In summary: Frequently making breaking changes is great for collaboratively drafting new software, but minor and patch releases are important for module consumers. Treating 1.0.0 as "special" fosters great OSS by acknowledging both of these needs.

jugglinmike commented Mar 1, 2013

The goal of getting people to publish as early as possible is well-served by a "special" interpretation of pre-1.0.0 releases.

It's good for developers to get their ideas published as early as possible--it sounds like everyone agrees on the basic tenets of OSS behind this claim. There is a negative effect to this, though: module consumers have no way of determining API stability.

Adopting a module is a commitment on the part of the consumer, and I think it's fair to say they want two things:

  1. The module not to break their application
  2. The module to enjoy the continued support/improvements that minor and patch releases provide

For example: a 2-month-old module at version 23.0.0 is extremely unattractive to me. By committing to it, I can expect a lot of maintenance cost relative to patches that are inevitably required.

Of course, a module at 0.23.0 is no different. But at least with that version, I know what I'm getting in to. I can easily compare that module with one at 1.4.3 and determine which is more likely to work and receive support in its current form for some time. If I like 0.23.0's API and I'm just making some dumb Twitter bot, then I'll use that. But If I'm building something to hand off to a client, then I'll use 1.1.3 with reasonable expectation of support.

Without the semantic distinction of 1.0.0, I have no way of predicting the risk I take committing to a given module.

In summary: Frequently making breaking changes is great for collaboratively drafting new software, but minor and patch releases are important for module consumers. Treating 1.0.0 as "special" fosters great OSS by acknowledging both of these needs.

@defunctzombie

This comment has been minimized.

Show comment
Hide comment
@defunctzombie

defunctzombie Mar 1, 2013

I will just add that a version called 0.0.0-pre or 0.0.1-pre or 1.0.0-pre are ALL valid versions and ways to indicate development status while still being published. npm even has a facility to publish such things but not have them be the default when someone installs your module.

I think mentally, people have an idea about 1.0.0 being the "first" version of something. All I will say is that no one is to be trusted :D

defunctzombie commented Mar 1, 2013

I will just add that a version called 0.0.0-pre or 0.0.1-pre or 1.0.0-pre are ALL valid versions and ways to indicate development status while still being published. npm even has a facility to publish such things but not have them be the default when someone installs your module.

I think mentally, people have an idea about 1.0.0 being the "first" version of something. All I will say is that no one is to be trusted :D

@dominictarr

This comment has been minimized.

Show comment
Hide comment
@dominictarr

dominictarr Mar 1, 2013

Owner

@jden setting version numbers that actually represent the changes in your api is much easier than writing bug free software. At least that way, you arn't gonna break dependent programs, because they have pulled in a breaking change that looked like a patch.

Owner

dominictarr commented Mar 1, 2013

@jden setting version numbers that actually represent the changes in your api is much easier than writing bug free software. At least that way, you arn't gonna break dependent programs, because they have pulled in a breaking change that looked like a patch.

@suarasaur

This comment has been minimized.

Show comment
Hide comment
@suarasaur

suarasaur Mar 1, 2013

@dominictarr I don't think anyone in this thread was disputing that. In @domenic's typology, adherents of both Orthodox and Reform semver preserve the meaning of minor version versus patch version.

suarasaur commented Mar 1, 2013

@dominictarr I don't think anyone in this thread was disputing that. In @domenic's typology, adherents of both Orthodox and Reform semver preserve the meaning of minor version versus patch version.

@indexzero

This comment has been minimized.

Show comment
Hide comment
@indexzero

indexzero Mar 1, 2013

Can I be the first to say Hasidic semver?

indexzero commented Mar 1, 2013

Can I be the first to say Hasidic semver?

@maxogden

This comment has been minimized.

Show comment
Hide comment
@maxogden

maxogden Mar 1, 2013

Collaborator

@indexzero only if you define its views as well

Collaborator

maxogden commented Mar 1, 2013

@indexzero only if you define its views as well

@indexzero

This comment has been minimized.

Show comment
Hide comment
@indexzero

indexzero Mar 1, 2013

No no. I'll leave that up to a true believer. I'm a "just for the holidays" kind of Hasidic semver follower.

indexzero commented Mar 1, 2013

No no. I'll leave that up to a true believer. I'm a "just for the holidays" kind of Hasidic semver follower.

@dominictarr

This comment has been minimized.

Show comment
Hide comment
@dominictarr

dominictarr Mar 1, 2013

Owner

The problem here I think is that people attach special meaning to certain version numbers like 1.0.0 means that the module is in some respect "finished" or "ready". I feel that is overloading versioning with meaning, if you are happy with your module, or are committed to backwards compatibility, then say so in your documentation.

Expecting people to read between the lines (numbers) on your version is not a good way to communicate a complicated idea like this.

That is not the spirit of semver - bumping a major version just means that a breaking change has been introduced, and that dependent modules may need to be altered to be compatible with the new version.

As pointed out by @domenic in the spec it actually says that version 0 means the version is not to be taken seriously,
and so the bump from 0 -> 1 does mean something.

I lament this, as I feel it introduces confusion, and encourages Sentimental Versioning.

Considering publishing SemVer@2.0.0: "The good parts". It would be a strict subset of SemVer, without the special zero range.

Note, SemVer@2.0.0 is a breaking change.

Owner

dominictarr commented Mar 1, 2013

The problem here I think is that people attach special meaning to certain version numbers like 1.0.0 means that the module is in some respect "finished" or "ready". I feel that is overloading versioning with meaning, if you are happy with your module, or are committed to backwards compatibility, then say so in your documentation.

Expecting people to read between the lines (numbers) on your version is not a good way to communicate a complicated idea like this.

That is not the spirit of semver - bumping a major version just means that a breaking change has been introduced, and that dependent modules may need to be altered to be compatible with the new version.

As pointed out by @domenic in the spec it actually says that version 0 means the version is not to be taken seriously,
and so the bump from 0 -> 1 does mean something.

I lament this, as I feel it introduces confusion, and encourages Sentimental Versioning.

Considering publishing SemVer@2.0.0: "The good parts". It would be a strict subset of SemVer, without the special zero range.

Note, SemVer@2.0.0 is a breaking change.

@suarasaur

This comment has been minimized.

Show comment
Hide comment
@suarasaur

suarasaur Mar 2, 2013

I don't see it as 1.0.0 having any special meaning, but rather the range <1.x has meaning distinct from >=1.x. This is useful for reasons outlined above in terms of encouraging releasing early and releasing often. This encouragement is not always needed!

However, it does seem to reflect my experience that most variation in a particular design comes at the beginning.

suarasaur commented Mar 2, 2013

I don't see it as 1.0.0 having any special meaning, but rather the range <1.x has meaning distinct from >=1.x. This is useful for reasons outlined above in terms of encouraging releasing early and releasing often. This encouragement is not always needed!

However, it does seem to reflect my experience that most variation in a particular design comes at the beginning.

@dominictarr

This comment has been minimized.

Show comment
Hide comment
@dominictarr

dominictarr Mar 3, 2013

Owner

Okay, so I think there are two things we are trying to do here - strictly indicate the nature of any change between versions (breaking, feature, and bugfix changes), and to communicate the current development status of a module.

These are two different problems!

They need two different solutions!

@jugglinmike @jden @domenic what about using a semver strictly without the funny 0- range,
and indicating the stability of your module in the documentation like node.js does?

Each core module in node has a stability index,

  • depreciated
  • experimental
  • unstable
  • stable
  • frozen
  • locked

described here http://nodejs.org/api/documentation.html

You could use a stability index for the module overall, or for individual features.

this information could even be put into the package json, and shown on npmjs.org

@izs what do you think?

Owner

dominictarr commented Mar 3, 2013

Okay, so I think there are two things we are trying to do here - strictly indicate the nature of any change between versions (breaking, feature, and bugfix changes), and to communicate the current development status of a module.

These are two different problems!

They need two different solutions!

@jugglinmike @jden @domenic what about using a semver strictly without the funny 0- range,
and indicating the stability of your module in the documentation like node.js does?

Each core module in node has a stability index,

  • depreciated
  • experimental
  • unstable
  • stable
  • frozen
  • locked

described here http://nodejs.org/api/documentation.html

You could use a stability index for the module overall, or for individual features.

this information could even be put into the package json, and shown on npmjs.org

@izs what do you think?

@domenic

This comment has been minimized.

Show comment
Hide comment
@domenic

domenic Mar 3, 2013

@dominictarr I don't know why you're insistent on coming up with your own solution to a problem that is already solved by the official semver spec. Smells like NIH to me.

what about using a semver strictly without the funny 0- range,

If by this you mean "advocate never releasing packages below 1.0.0," then OK, that's fine. That sidesteps the whole debate, and from there, you can advocate anything you want for stability, and maybe people will follow you, or maybe they'll use the tools we already have.

What I don't like is advocating releasing packages below 1.0.0 with semantics different from those of semver.org. By doing so you're communicating to people that my 0.x packages will be stable and not have API changes from 0.1 to 0.2 or even from 0.1.0 to 0.1.1, which they very well might. Even Iconoclast Semverists will be hurt by such advocacy.

domenic commented Mar 3, 2013

@dominictarr I don't know why you're insistent on coming up with your own solution to a problem that is already solved by the official semver spec. Smells like NIH to me.

what about using a semver strictly without the funny 0- range,

If by this you mean "advocate never releasing packages below 1.0.0," then OK, that's fine. That sidesteps the whole debate, and from there, you can advocate anything you want for stability, and maybe people will follow you, or maybe they'll use the tools we already have.

What I don't like is advocating releasing packages below 1.0.0 with semantics different from those of semver.org. By doing so you're communicating to people that my 0.x packages will be stable and not have API changes from 0.1 to 0.2 or even from 0.1.0 to 0.1.1, which they very well might. Even Iconoclast Semverists will be hurt by such advocacy.

@dominictarr

This comment has been minimized.

Show comment
Hide comment
@dominictarr

dominictarr Mar 3, 2013

Owner

Okay, so I'll advocate just not using the 0 range, and starting from 1.

It seems that people want to communicate about the stability of their modules,
and I think it's confusing to for major version to indicate stability.

So, what do you think about using the stability index?

Owner

dominictarr commented Mar 3, 2013

Okay, so I'll advocate just not using the 0 range, and starting from 1.

It seems that people want to communicate about the stability of their modules,
and I think it's confusing to for major version to indicate stability.

So, what do you think about using the stability index?

@domenic

This comment has been minimized.

Show comment
Hide comment
@domenic

domenic Mar 3, 2013

I think it's not confusing to use the major version to indicate stability, and plan to continue to do so. Happy to let others chime in though :)

domenic commented Mar 3, 2013

I think it's not confusing to use the major version to indicate stability, and plan to continue to do so. Happy to let others chime in though :)

@dominictarr

This comment has been minimized.

Show comment
Hide comment
@dominictarr

dominictarr Mar 3, 2013

Owner

If >= 1.0.0 means "stable" and version numbers in the 0.x.y range mean nothing, then you are between a rock and a hard place, because there is no way to have an unstable module with meaningful version numbers. That is what I want.

Owner

dominictarr commented Mar 3, 2013

If >= 1.0.0 means "stable" and version numbers in the 0.x.y range mean nothing, then you are between a rock and a hard place, because there is no way to have an unstable module with meaningful version numbers. That is what I want.

@izs

This comment has been minimized.

Show comment
Hide comment
@izs

izs Mar 3, 2013

Look. You guys. You'll never ever settle this.

Versions mean whatever the author means by that version number. How do you
know what the author meant? Read the docs, or just ask them.

This effort to reduce away that need for actual human investigation is a
bit foolish. That's why npm and node-semver make no claims about what
"1.0.0" means, except that it is > 0.88.67 and < 2.25.4.

Now, if Domenic want to day that 1.0.0 is when his module gives him warm
fuzzy secure feelings, then great. If Dominic wants to say that 1.0.0 is
simply the first breaking change, then that's also fine. If I'm using your
module, I have to know how it work anyway, an knowing what the version
means is only a tiny part of that.

Given how people tend to use versions, and how the "1.3.x" and ~ style
comparators work, it's easier if patch versions are "pretty safe" to
update to, and major version bumps are "omg rewrite", and minor versions
are somewhere in between.

But we are not prescriptivist here! The ordering is defined, and the
comparators are there. These are the tools by which actual humans define
semantics that make sense in context. The "sem" in "semver" is what you put
there. It's not in the numbers themselves. It requires understanding and
trust of the author's approach. You're using their code, so you'd better
trust them already, and probably read the docs at least once.

This is a social problem which cannot be solved with a technical solution,
and any "1.0 means this or that" is jut propaganda to try to get other
people to be like you. Which is part of the process, of course. But as this
is an anarchic system, the benefit to Domenic of accepting Dominic's
aberrant use of the first natural number is pretty high, so it would be
wise to just get over it, and accept the difference, where it matters.

If, in the fullness of time, we abandon 1.0 magic, or change it, as we have
"beg the question", then we'll just have to live with it. That's how
language works, and version numbers are just a structured token in the
complex language game of code reuse. They who write quality modules will
decide the rules of the game.

On Saturday, March 2, 2013, Dominic Tarr wrote:

So, this is what it really boils down to for me, why I don't like the
0.x.y range rule:

It discourages module authors from using semver effectively during periods
when their module is unstable.

And unstable/experimental modules are the modules that benefit most from
semver!


Reply to this email directly or view it on GitHubhttps://github.com//issues/2#issuecomment-14342163
.

izs commented Mar 3, 2013

Look. You guys. You'll never ever settle this.

Versions mean whatever the author means by that version number. How do you
know what the author meant? Read the docs, or just ask them.

This effort to reduce away that need for actual human investigation is a
bit foolish. That's why npm and node-semver make no claims about what
"1.0.0" means, except that it is > 0.88.67 and < 2.25.4.

Now, if Domenic want to day that 1.0.0 is when his module gives him warm
fuzzy secure feelings, then great. If Dominic wants to say that 1.0.0 is
simply the first breaking change, then that's also fine. If I'm using your
module, I have to know how it work anyway, an knowing what the version
means is only a tiny part of that.

Given how people tend to use versions, and how the "1.3.x" and ~ style
comparators work, it's easier if patch versions are "pretty safe" to
update to, and major version bumps are "omg rewrite", and minor versions
are somewhere in between.

But we are not prescriptivist here! The ordering is defined, and the
comparators are there. These are the tools by which actual humans define
semantics that make sense in context. The "sem" in "semver" is what you put
there. It's not in the numbers themselves. It requires understanding and
trust of the author's approach. You're using their code, so you'd better
trust them already, and probably read the docs at least once.

This is a social problem which cannot be solved with a technical solution,
and any "1.0 means this or that" is jut propaganda to try to get other
people to be like you. Which is part of the process, of course. But as this
is an anarchic system, the benefit to Domenic of accepting Dominic's
aberrant use of the first natural number is pretty high, so it would be
wise to just get over it, and accept the difference, where it matters.

If, in the fullness of time, we abandon 1.0 magic, or change it, as we have
"beg the question", then we'll just have to live with it. That's how
language works, and version numbers are just a structured token in the
complex language game of code reuse. They who write quality modules will
decide the rules of the game.

On Saturday, March 2, 2013, Dominic Tarr wrote:

So, this is what it really boils down to for me, why I don't like the
0.x.y range rule:

It discourages module authors from using semver effectively during periods
when their module is unstable.

And unstable/experimental modules are the modules that benefit most from
semver!


Reply to this email directly or view it on GitHubhttps://github.com//issues/2#issuecomment-14342163
.

@maxogden

This comment has been minimized.

Show comment
Hide comment
@maxogden

maxogden Mar 3, 2013

Collaborator

... and my axe!

Collaborator

maxogden commented Mar 3, 2013

... and my axe!

@dominictarr

This comment has been minimized.

Show comment
Hide comment
@dominictarr

dominictarr Mar 4, 2013

Owner

a tool for inserting stability messages into your README and package.json

Owner

dominictarr commented Mar 4, 2013

a tool for inserting stability messages into your README and package.json

@madbence madbence referenced this issue Jul 19, 2014

Closed

Add slimver #33

demands referenced this issue in goodeggs/mongoose-webdriver Oct 13, 2014

Changes that should probably be a part of our yeoman generator
Also things I had to do:

git commit -m "Module generated by goodeggs-npm"
git push --set-upstream origin master

Add a project description on GitHub

hurrymaplelad referenced this issue in npm/init-package-json Oct 27, 2014

Default to version 1.0.0
Since the SemVer spec is weirdly magical about 0.x.y versions, and we
cannot ever hope to get everyone to believe what the correct
interpretation of 0.x versions are, let's just skip them entirely.
@suarasaur

This comment has been minimized.

Show comment
Hide comment
@suarasaur

suarasaur May 26, 2015

This issue is still showing up on my personal "open issues mentioning you" list, limiting its utility. Could you please consider closing it?

suarasaur commented May 26, 2015

This issue is still showing up on my personal "open issues mentioning you" list, limiting its utility. Could you please consider closing it?

@isaacs

This comment has been minimized.

Show comment
Hide comment
@isaacs

isaacs May 26, 2015

+1 for closing this 2-year-old testament to defacto vs dejure specifications.

isaacs commented May 26, 2015

+1 for closing this 2-year-old testament to defacto vs dejure specifications.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment