Added description for pre-stable public API versioning #127
Conversation
But that is exactly the point in saying that "Anything may change at any time." Version At the same time, it is an interesting proposal to have a structured approach to For the time being, it sounds like you could have a node.js specific recommendation for versioning 0.* packages given to node package authors. After all, the rule you propose is an extra restriction beyond what SemVer requires, thus following it is compatible with SemVer. |
|
While anything may change before 1.0.0 is released and you are taking on risk, I think it is valuable to have some clear meaning behind pre-stable versioning rather than an arbitrary scheme for each package. This solution is not just for node.js packages, looking at Jekyll's history it seems to have followed this pattern of updating minor versions when API-breaking changes occurred and patch versions for features. I think people arrive at this conclusion independently when developing packages using semver, and it would be nice to formalize it. |
|
+1. (Github should really add a +1 button or something like that.) In my opinion, it is very important to have an actual set of rules for 0.x.y versions. |
|
Any reason to not add meaning to pre 1.0.0 versioning? Otherwise, can this pull get accepted? |
|
I have been thinking about this for a while, and I think this is a great addition for 3.0.0. If you are using SemVer, why not have the same rigor in versions prior to 1.0.0? It will also help pre-1.0.0 consumers know the possible level of pain in updating. Most beneficially, it allow us to specify version range dependencies on pre-1.0.0 instead of just fixed versions. |
|
An often overlooked principle of SemVer is that as soon as you have a stable API, you should be past 1.0.0. Many projects with stable APIs are still in 0.x.y. A particular dependency for one of my projects is still at 0.0.3, but it already has a stable API. Without some strict version system for the 0.x.y phase, it would be hard to manage dependencies not yet at 1.0.0. |
|
well, your 0.0.3 dependency then doesn't conform to SemVer. So no matter what SemVer specifies you'll never be able to use it correctly, until they switch to SemVer. I'm opposed to the change. There is a stable and an unstable state, Semver draws the line (arbitrarily) at 1.0.0. No matter what you specify there will always be a line somewhere. accept this, and then start discussing specification of the pre-pre-stable state. Imo stick to simple, draw the line at 1.0.0. |
|
There is nothing currently stating 0.0.3 is not a valid semver (no minimum version is ever specified). Even with the additions specified here 0.0.3 conforms if you have 3 revs with no breaking changes. 0.0.1 would become the default first version as all initial edits are non-breaking in the first addition. As for Stable the 1.0.0 line is the sand is there for the CONSUMER to know that they can depend on notifications of breaking changes with major versions. It has nothing to do with how well the Public API was designed. Pre 1.0.0 will still be considered unstable even if it actually is. This PR helps to partially remove that arbitrary line for consumers while still leaving a version range for anything goes development. |
|
This PR should also be updated to address the FAQ section questions about 0.y.z development. |
|
I've made a similar pull request and one of these two should be accepted. "Anything may change at any time." literally describes any version, but only after public release does it denote a change required in the version (Major version bump). I've documented my thoughts in the other pull request, but this really has to be looked into. |
|
|
||
| The simplest thing to do is start your initial development release at 0.1.0 | ||
| and then increment the minor version for each subsequent release. | ||
|
|
There was a problem hiding this comment.
It would make me very happy to at least see this part accepted.
|
The real problem here is that authors are afraid to make their projects 1.0.0, not that the spec is a free-for-all during version 0.y.z. Since this is a social problem, a social solution would be better. We should all be pressuring authors of widely used packages to go 1.0.0. Maybe we can have an International 1.0 Day and raise awareness around this issue. Adding rules to 0.y.z won't solve this problem, it will only make authors of new software into liars or non-Semver users. Besides, until a public API has been defined, the rules of Semver are meaningless. 0.y.z is where you establish a public API. It's an unreasonable burden to require that new projects define a public API with their very first commit. |
|
Tom, a first commit is not a release. A release is putting your package in a package manager index. Saying "this is the public API" by then is pretty damn reasonable. On Wed, Jul 2, 2014 at 4:34 PM, Tom Preston-Werner <notifications@github.com
Kurtis Rainbolt-Greene, Hacker |
Perhaps. Or perhaps a release is pushing your software to GitHub (golang, for instance). Different package management paradigms would think differently about what a release is.
Then why not also mark your project as 1.0.0? If you're going to be rigorously tracking backwards compatibility, then you're ready to be 1.0.0. Semver is already very well suited to tracking changes as long as you're 1.0.0 or above. Adding those same rules to 0.y.z, except pushed down a slot, is redundant and confusing. I don't think merging this PR will solve the real problem. Only PEOPLE can solve this problem. If, indeed, people are SO averse to making the 1.0.0 leap, then a better solution would be to introduce epoch version to Semver. Then we'd have e.x.y.z and 0.0.y.z could be free-for-all and 0.1.y.z. would be for "initial development but API-tracking" status. Then the leap to the 1.0.0.0 mark would signify that the authors are finally brave enough to tell the word to use their software. But I'd rather fix people's perception of 1.0.0 than add more complexity to Semver. |
You closed my pull request that tried to solve the problem in order to I'm out. On Wed, Jul 2, 2014 at 4:54 PM, Tom Preston-Werner <notifications@github.com
Kurtis Rainbolt-Greene, Hacker |
|
I agree with @mojombo . I like the 'social problem' definition of this issue. That is exactly what it is. |
I can dig that. I experience the problem of "not going for 1.0.0" as well and the problem I face is mostly that I am not really done with what I have in mind for 1.0.0 but don't have the time to finish for example and just want people to be able to use it nonetheless. Or maybe I didn't expect things to work out so well that it could've easily been 1.0.0 instead of 0.5.2 and didn't went later back to re-releasing the same version as 1.0.0. (The 1.0.0 day could help here I guess.) In that sense, why do we need versions prior 1.0.0 anyway? Shouldn't pre-releases be enough? Will that solve our problem though (because you can experience the same issue with pre-releases just as well)? |
@krainboltgreene Which PR is that? I closed one on a similar subject from @loz yesterday, but your #152 is still open. I will comment over there as well. I am certainly not intending to insult you, only to logically argue for what I think is best for the spec. I'm sorry it came out that way, I really appreciate your involvement and feedback on Semver. |
@FichteFoll I don't think it's enough. The initial development phase of a project is very different from every phase afterwards (and making it easy to follow Semver from the start is critical). Semver embraces this difference and allows space for it in 0.y.z. Dealing with dependence on a 0.y.z version is simple. Since no promises are made about how the API will change, you should only depend on exact versions. Any new versions must be fully tested before you rely on them. @haacked What are your latest thoughts on this matter? I'm pretty strongly opposed to rigid rules that must be followed during the 0.y.z phase. |
|
Alright, I agree that the "before 1.0.0" time (the process of establishing the first API that you want to be considered as stable and people to be abl to depend on) is significantly different to altering that previously stable API. In that sense, |
|
@FichteFoll In what way do you think it is confusing for some? I'm open to refining that wording if it will clarify things for anyone. |
|
@mojombo, after reading your other comment I think it's missing is a clarification on how to handle depending on versions I know that this is what |
|
There's a faq entry;
If you add;
wouldn't that cover it? |
|
Yes, this is what I had in mind. Well, practically you can use ranges but only if you tested the versions before, however I think that a decent developer can make that conclusion on his own. |
|
Current SemVer has two ways to be "prerelease", the 0.x.x series and anything with a -prerelease tag on it. Why two? Well it's just a fact of history at this point. If we ever get to a 3.x.x series in SemVer, I hope we close that loop-hole permanently. I see nothing wrong with starting out at 1.0.0-unstable, but then we have the problem where -unstable has higher precedence than -beta or -prerelease and that's just another reason why I have been tempted to propose yet another standard. Basically, the problem that @ChrisWren is trying to solve here, stems directly from the 0.x.x loop-hole. Require the prerelease tag and remove the loop-hole, the problem goes away, you have the full semantics we are looking for. Here's a proposed workaround that I am pretty sure the current standard allows: 0.0.1-dev // Start of sprint, unpublished except for commits. Notice how many times I had to use the word "release" to describe what happened? SemVer seems to imply tighter constraints on that word than most developers actually use in practice. The 1.0.0-a.ring.0 version is a published prerelease. Even the 0.0.1-dev version was "released" by the developer to the rest of the team the instant they committed their change. Unfortunately, the word "published" is not mentioned in the spec, despite the fact that it appears to be what was actually meant by its use of "released". We have a stable spec at 2.0.0, with fairly good adoption at this point and while I do feel there's some work to be done within that scope, I think there's good reason to move on to 3.x.x discussions. I believe I just offered an acceptable workaround for @ChrisWren, that has a high probability of not breaking anything and without changing the 2.0.0 spec. If somebody cries foul over the missing 1.0.0 (no tags) version, who cares? |
|
@ChrisWren, please close this issue at your earliest possible convenience. Thank you. |
|
Closing & re-opening to trigger CI |
alexandrtovmach
added
extend
|
Is there any reason the maintainers have not closed this PR? There are also several other very old ones with clear indications that they are not going to be accepted. |
|
@adamralph Thank you for paying attention to that, I'll go through staled things a bit later |
Fix Japanese wording consistency and typo
When reading the description for major version zero I came across the line "Anything may change
at any time." I would like to create a more clear explanation of how versioning should take place before the first stable version of the public API so that developers can have meaning behind their pre-stable versioning.
This is especially an issue in node.js development as by default saved modules will pick up new patch versions but not new minor versions. If developers don't properly version their modules in a pre-stable state they can potentially break when users pick up new patch versions.
To define this pre-stable state I have proposed moving the definition for major and minor changes to the right, meaning that API-breaking changes result in a minor version being incremented and both backwards-compatible functional additions as well as bug fixes result in a patch version being incremented.