Ideas #354

New Issue

GiteaMirror · 2026-02-17T11:55:08-06:00

GiteaMirror commented

2026-02-17 11:55:08 -06:00

Originally created by @JonathanWilbur on GitHub (Dec 29, 2018).

Non-public versions start at 0.0.0, where version 0.0.0 may only contain immutable / static data structures and constants and comments.
As soon as the code contains any functions, methods, calculations, or evaluation of any expressions or conditions, it then becomes 0.1.0.
For non-public APIs, since the entire thing is assumed to be buggy or inadequate for public release (hence, private), the meaning of the numbers should "shift over," such that an increment in the minor version number indicates a backwards-incompatible change with a previous version, and an increment of the patch number indicates a backwards-compatible change or improvement in functionality.

Originally created by @JonathanWilbur on GitHub (Dec 29, 2018). * Non-public versions start at 0.0.0, where version 0.0.0 may only contain immutable / static data structures and constants and comments. * As soon as the code contains any functions, methods, calculations, or evaluation of any expressions or conditions, it then becomes 0.1.0. * For non-public APIs, since the entire thing is assumed to be buggy or inadequate for public release (hence, private), the meaning of the numbers should "shift over," such that an increment in the minor version number indicates a backwards-incompatible change with a previous version, and an increment of the patch number indicates a backwards-compatible change or improvement in functionality.

GiteaMirror added the consensus seeking question labels 2026-02-17 11:55:08 -06:00

GiteaMirror commented

2026-02-17 11:55:10 -06:00

@jwdonahue commented on GitHub (Aug 16, 2019):

For non-public APIs, since the entire thing is assumed to be buggy or inadequate for public release (hence, private), the meaning of the numbers should "shift over," such that an increment in the minor version number indicates a backwards-incompatible change with a previous version, and an increment of the patch number indicates a backwards-compatible change or improvement in functionality.

Absolutely not. This implies that a developer even knows, at the time of publication, whether the changes are breaking. We should not specify behaviors that cannot be reasonably enforced.

As for the rest, there is nothing in the spec that suggests you can't start at 0.0.0. The FAQ recommends using 0.1.0, but the FAQ is not part of the spec.

@jwdonahue commented on GitHub (Aug 16, 2019): > For non-public APIs, since the entire thing is assumed to be buggy or inadequate for public release (hence, private), the meaning of the numbers should "shift over," such that an increment in the minor version number indicates a backwards-incompatible change with a previous version, and an increment of the patch number indicates a backwards-compatible change or improvement in functionality. Absolutely not. This implies that a developer even knows, at the time of publication, whether the changes are breaking. We should not specify behaviors that cannot be reasonably enforced. As for the rest, there is nothing in the spec that suggests you can't start at 0.0.0. The FAQ recommends using 0.1.0, but the FAQ is not part of the spec.

GiteaMirror commented

2026-02-17 11:55:11 -06:00

@ljharb commented on GitHub (Aug 16, 2019):

@jwdonahue iirc a previous version of the semver spec said that x was major, y was minor, and z was patch, and that it went x.y.z or 0.x.y or 0.0.y. The current version, I believe, says everything is potentially breaking pre-1.0, which is much less useful. Every project I maintain that's not yet at v1 follows the earlier form, and it's quite useful to do what semver does best - convey breakage, and non-breakage.

@ljharb commented on GitHub (Aug 16, 2019): @jwdonahue iirc a previous version of the semver spec said that `x` was major, `y` was minor, and `z` was patch, and that it went `x.y.z` or `0.x.y` or `0.0.y`. The current version, I believe, says everything is potentially breaking pre-1.0, which is much less useful. Every project I maintain that's not yet at v1 follows the earlier form, and it's quite useful to do what semver does best - convey breakage, and non-breakage.

GiteaMirror commented

2026-02-17 11:55:12 -06:00

@jwdonahue commented on GitHub (Aug 16, 2019):

I understand it is a well trodden convention to shift the meanings to the right one place for the 0.a.b prerelease forms, but it should not be written into the spec. Remember that the spec defines the rules for producers, but it also implies the valid set of rules that consumers might reasonably apply when deciding to take one version of a package over another.

Don't confuse the place holder variable names in a field position with the meaning of that position. The fields are named Major.Minor.Patch. We commonly use variables as place holders when discussing version strings, but they have no meaning other than that which is assigned to their positions.

The spec explicitly states that all semantic meaning other than the prerelease state of the API or package, goes out the window for SemVer strings with a zero major version or an appended prerelease tag. As a publisher, you can try to suggest that minor bumps are breaking and path bumps aren't if you wish, but as a consumer, I must treat all prerelease versions as potentially breaking, because that is implied by the wording of the spec.

Your idea of non-public is not well defined. In SemVer there is what has been published (public) and therefore versioned, and that which has not been published, and therefore does not have to carry a SemVer string along with any of its semantics. The spec does not speak to your internal processes or conventions, nor should it ever try.

If you are looking for tooling that properly handles the convention of shifting the breaking change field over one to the right, changing the spec will not necessarily achieve your goal. It would be a breaking change in the spec and might never be adopted by any of the package tool owners.

@jwdonahue commented on GitHub (Aug 16, 2019): I understand it is a well trodden convention to shift the meanings to the right one place for the 0.a.b prerelease forms, but it should not be written into the spec. Remember that the spec defines the rules for producers, but it also implies the valid set of rules that consumers might reasonably apply when deciding to take one version of a package over another. Don't confuse the place holder variable names in a field position with the meaning of that position. The fields are named Major.Minor.Patch. We commonly use variables as place holders when discussing version strings, but they have no meaning other than that which is assigned to their positions. The spec explicitly states that all semantic meaning other than the prerelease state of the API or package, goes out the window for SemVer strings with a zero major version or an appended prerelease tag. As a publisher, you can **_try_** to suggest that minor bumps are breaking and path bumps aren't if you wish, but as a consumer, I must treat all prerelease versions as potentially breaking, because that is implied by the wording of the spec. Your idea of non-public is not well defined. In SemVer there is what has been published (public) and therefore versioned, and that which has not been published, and therefore does not have to carry a SemVer string along with any of its semantics. The spec does not speak to your internal processes or conventions, nor should it ever try. If you are looking for tooling that properly handles the convention of shifting the breaking change field over one to the right, changing the spec will not necessarily achieve your goal. It would be a breaking change in the spec and might never be adopted by any of the package tool owners.

GiteaMirror commented

2026-02-17 11:55:12 -06:00

@jwdonahue commented on GitHub (Aug 16, 2019):

I would also contend that VersionMeta and VersionSchema are better suited for all future tooling. I currently view SemVer as a dead-end. A version 3.0.0 would be a waste of energy if it does not more completely cover the requirements of DevOps systems, which I think may be your motivation here.

@jwdonahue commented on GitHub (Aug 16, 2019): I would also contend that [VersionMeta ](http://versionmeta.org/)and [VersionSchema](http://versionSchema.org/) are better suited for all future tooling. I currently view SemVer as a dead-end. A version 3.0.0 would be a waste of energy if it does not more completely cover the requirements of DevOps systems, which I think may be your motivation here.

GiteaMirror commented

2026-02-17 11:55:13 -06:00

@grv87 commented on GitHub (Aug 23, 2019):

@jwdonahue, although I mostly agree with you, I think that here

This implies that a developer even knows, at the time of publication, whether the changes are breaking.

you miss the point that even after public v1 release developer may be wrong whether the changes are breaking. Spec just implies that he knows what is compatible and what is not. What's the difference between initial development and public release? It's always the best judgement and nothing more.

@JonathanWilbur, @ljharb - have you seen the previous discussion on pre-releases in #221?
The common result there was that magic zero rule should be dropped.
Backward-incompatible change should lead to major version update from the very beginning.
No separate initial development phase.

@grv87 commented on GitHub (Aug 23, 2019): @jwdonahue, although I mostly agree with you, I think that here > This implies that a developer even knows, at the time of publication, whether the changes are breaking. you miss the point that even after public `v1` release developer may be wrong whether the changes are breaking. Spec just implies that he knows what is compatible and what is not. What's the difference between initial development and public release? It's always the best judgement and nothing more. @JonathanWilbur, @ljharb - have you seen the previous discussion on pre-releases in #221? The common result there was that *magic zero* rule should be dropped. Backward-incompatible change should lead to major version update from the very beginning. No separate *initial development* phase.

GiteaMirror commented

2026-02-17 11:55:14 -06:00

@ljharb commented on GitHub (Aug 23, 2019):

That issue didn’t reach a consensus that i can see; but the OP imo is a much more useful semver spec than the current one.

If pre-1.0 versions are banned, that might work too, but that doesn’t seem practical in an ecosystem that already has many.

@ljharb commented on GitHub (Aug 23, 2019): That issue didn’t reach a consensus that i can see; but the OP imo is a much more useful semver spec than the current one. If pre-1.0 versions are banned, that might work too, but that doesn’t seem practical in an ecosystem that already has many.

GiteaMirror commented

2026-02-17 11:55:15 -06:00

@jwdonahue commented on GitHub (Aug 24, 2019):

@grv87

you miss the point that even after public v1 release developer may be wrong whether the changes are breaking.

I may be missing something, but that point isn't one of them. Consider that some changes will break some customers and not others. What then? Do I release one package versioned for one set of customers and another for the rest? Of course not.

The whole point of SemVer is that it communicates risk to our customers. I may not know for certain that any of my customers will be broken by my next release, but I may be so risk averse, due to contractual or liability concerns, that I mark every release as breaking. I make the determination to bump the major version, based on my knowledge of my relationship with my customers and what I know of the implied semantics for the version string.

So yes, I guess we agree:

It's always the best judgement and nothing more.

@jwdonahue commented on GitHub (Aug 24, 2019): @grv87 >you miss the point that even after public v1 release developer may be wrong whether the changes are breaking. I may be missing something, but that point isn't one of them. Consider that some changes will break some customers and not others. What then? Do I release one package versioned for one set of customers and another for the rest? Of course not. The whole point of SemVer is that it communicates risk to our customers. I may not know for certain that **any** of my customers will be broken by my next release, but I may be so risk averse, due to contractual or liability concerns, that I mark every release as breaking. I make the determination to bump the major version, based on my knowledge of my relationship with my customers and what I know of the implied semantics for the version string. So yes, I guess we agree: > It's always the best judgement and nothing more.

GiteaMirror commented

2026-02-17 11:55:16 -06:00

@jwdonahue commented on GitHub (Aug 24, 2019):

@ljharb, I think it just adds unneeded complexity. Much simpler to drop the leading major zero from the spec and just go with the -prerelease tag semantics. That would give us major.minor.patch to at least hint at what we think we're shipping. Is there a difference between 0.1.0 .. 0.9.0 and 0.1.0-a.dev .. 0.9.0-a.dev? In both cases, I can still have 1.0.0-a.ReleaseCandidate.01 and etc. So my question is why do we really need both prerelease modes? Which is more semantically complete?

@jwdonahue commented on GitHub (Aug 24, 2019): @ljharb, I think it just adds unneeded complexity. Much simpler to drop the leading major zero from the spec and just go with the -prerelease tag semantics. That would give us major.minor.patch to at least hint at what we think we're shipping. Is there a difference between 0.1.0 .. 0.9.0 and 0.1.0-a.dev .. 0.9.0-a.dev? In both cases, I can still have 1.0.0-a.ReleaseCandidate.01 and etc. So my question is why do we really need both prerelease modes? Which is more semantically complete?

GiteaMirror commented

2026-02-17 11:55:16 -06:00

@ljharb commented on GitHub (Aug 24, 2019):

@jwdonahue typically in the js ecosystem, 0.2.1 is a non breaking change from 0.2.0, and 0.3.0 is a breaking change from 0.2.x, despite what the semver spec says. #221 would have codified that much more useful (than prereleases and also than the current 0.x spec) behavior.

@ljharb commented on GitHub (Aug 24, 2019): @jwdonahue typically in the js ecosystem, 0.2.1 is a non breaking change from 0.2.0, and 0.3.0 is a breaking change from 0.2.x, despite what the semver spec says. #221 would have codified that much more useful (than prereleases and also than the current 0.x spec) behavior.

GiteaMirror commented

2026-02-17 11:55:17 -06:00

@jwdonahue commented on GitHub (Aug 24, 2019):

despite what the semver spec says

Actually because it allows that, and any other possible variation.

I just don't think the SemVer spec should codify that particular behavior. You are proposing a tightening of a spec that is already a lowest common denominator kind of thing. Just go read all of the issues that have been posted here and you will find there is no end to the variations that could be codified.

I prefer to put my money and efforts into http://versionmeta.org and http://versionschema.org, so that we can avail ourselves of whatever practices best fit our customer's needs.

@jwdonahue commented on GitHub (Aug 24, 2019): > despite what the semver spec says Actually **because** it allows that, and any other possible variation. I just don't think the SemVer spec should codify that particular behavior. You are proposing a tightening of a spec that is already a lowest common denominator kind of thing. Just go read all of the issues that have been posted here and you will find there is no end to the variations that _could_ be codified. I prefer to put my money and efforts into [http://versionmeta.org](http://versionmeta.org) and [http://versionschema.org](http://versionschmea.org), so that we can avail ourselves of whatever practices best fit our customer's needs.

GiteaMirror commented

2026-02-17 11:55:18 -06:00

@jwdonahue commented on GitHub (Aug 24, 2019):

I personally do not believe that my prerelease sequence of version strings have to bear any resemblance to official releases. I am aware of development practices that publish continuous integration and daily builds with a build number, branch, machine or developer alias, and the Git hash that produced it. Then every now and then, the powers that be, decide that one of those is worthy of flight testing to a wider audience than internal developers and partners, so it is built by one particularly well secured cluster of build machines and released with nothing but that build number on it.

There are many best-of-breed practices in this space. I don't have any problem with folks bending the SemVer rules a bit. Designating the minor field for breaking changes in your prerelease strings is already allowed under SemVer. Your doing that does not break my standard ingestion rules that forbid all prerelease packages from finding their way into my production code. If I become aware of your practices, I might tweak my rules to take that into account when deciding how many automated resources to put into evaluating your prereleases, but I would want to see a lot of evidence that you have been reliably signalling those breaking changes.

I wouldn't like being told that my prereleases had to conform to your tighter standard. My prerelease stream has a much lower bar to pass on that breaking/non-breaking change dimension. My release stream has breaking changes in it that affect less than 1% of my customers, while my prerelease stream probably affects closer to 20% or more. That's why I tag it as prerelease. Any 0.0.z prerelease is likely to contain breaking changes.

@jwdonahue commented on GitHub (Aug 24, 2019): I personally do not believe that my prerelease sequence of version strings have to bear any resemblance to official releases. I am aware of development practices that publish continuous integration and daily builds with a build number, branch, machine or developer alias, and the Git hash that produced it. Then every now and then, the powers that be, decide that one of those is worthy of flight testing to a wider audience than internal developers and partners, so it is built by one particularly well secured cluster of build machines and released with nothing but _that_ build number on it. There are many best-of-breed practices in this space. I don't have any problem with folks bending the SemVer rules a bit. Designating the minor field for breaking changes in your prerelease strings is already allowed under SemVer. Your doing that does not break my standard ingestion rules that forbid all prerelease packages from finding their way into my production code. If I become aware of your practices, I might tweak my rules to take that into account when deciding how many automated resources to put into evaluating your prereleases, but I would want to see a lot of evidence that you have been reliably signalling those breaking changes. I wouldn't like being told that _my_ prereleases had to conform to your tighter standard. My prerelease stream has a much lower bar to pass on that breaking/non-breaking change dimension. My release stream has breaking changes in it that affect less than 1% of my customers, while my prerelease stream probably affects closer to 20% or more. That's why I tag it as prerelease. Any 0.0.z prerelease is likely to contain breaking changes.

GiteaMirror commented

2026-02-17 11:55:19 -06:00

@grv87 commented on GitHub (Aug 24, 2019):

typically in the js ecosystem, 0.2.1 is a non breaking change from 0.2.0, and 0.3.0 is a breaking change from 0.2.x, despite what the semver spec says

@jwdonahue is right, proposed behavior doesn't violate current spec.
If js folks want this, they could extend SemVer with custom extra requirements, here.

@JonathanWilbur, @ljharb, @isaacs - was this proposition discussed inside js community?

@grv87 commented on GitHub (Aug 24, 2019): > typically in the js ecosystem, 0.2.1 is a non breaking change from 0.2.0, and 0.3.0 is a breaking change from 0.2.x, despite what the semver spec says @jwdonahue is right, proposed behavior doesn't violate current spec. If js folks want this, they could extend SemVer with custom extra requirements, [here](https://docs.npmjs.com/files/package.json#version). @JonathanWilbur, @ljharb, @isaacs - was this proposition discussed inside js community?

GiteaMirror commented

2026-02-17 11:55:20 -06:00

@1atAlcone commented on GitHub (Feb 13, 2025):

@

@1atAlcone commented on GitHub (Feb 13, 2025): @[]()

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/semver#354