Misunderstaning of changing minor and patch if major is changed #84

New Issue

GiteaMirror · 2026-02-17T11:10:37-06:00

GiteaMirror commented

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

Originally created by @bessarabov on GitHub (Jul 2, 2013).

Current version of semver (2.0.0) has such text:

8 Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API. It MAY include minor and patch level changes. Patch and minor version MUST be reset to 0 when major version is incremented.

For me the phrase It MAY include minor and patch level changes. is very unclear. When reading this for the first time I thought that it is possible to change from 1.2.3 to 2.3.4 in one step. Then I read the second phrase Patch and minor version MUST be reset to 0 when major version is incremented. and I understood that that MAY is written in case there are some minor and patch that are not zeroes. For example change from 1.0.0 to 2.0.0 is done without minor and patch change, but the change from 1.2.3 to 2.0.0 is done with minor and patch change.

My proposal is to write this thing more clearly. Maybe just to remove "MAY" phrase:

8 Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API. Patch and minor version MUST be reset to 0 when major version is incremented.

Originally created by @bessarabov on GitHub (Jul 2, 2013). Current version of semver (2.0.0) has such text: > 8 Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API. It MAY include minor and patch level changes. Patch and minor version MUST be reset to 0 when major version is incremented. For me the phrase `It MAY include minor and patch level changes.` is very unclear. When reading this for the first time I thought that it is possible to change from 1.2.3 to 2.3.4 in one step. Then I read the second phrase `Patch and minor version MUST be reset to 0 when major version is incremented.` and I understood that that `MAY` is written in case there are some minor and patch that are not zeroes. For example change from 1.0.0 to 2.0.0 is done without minor and patch change, but the change from 1.2.3 to 2.0.0 is done with minor and patch change. My proposal is to write this thing more clearly. Maybe just to remove "MAY" phrase: > 8 Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API. Patch and minor version MUST be reset to 0 when major version is incremented.

GiteaMirror closed this issue

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

GiteaMirror commented

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

@haacked commented on GitHub (Jul 2, 2013):

Ok, so I just merged @EddieGarmon's change. But I kind of agree with you. Do we even need that phrase? It seems to me that it's obvious that other minor changes might be included with incompatible changes.

Here's a couple of proposals. Would you mind sending a pull request with the one you like best?

Here's what you wrote:

Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API. Patch and minor version MUST be reset to 0 when major version is incremented.

And here's an alternative that might clarify a bit more what we mean.

Major version X (X.y.z | X > 0) MUST be incremented if a set of changes includes a backwards incompatible change to the public API. Patch and minor version MUST be reset to 0 when major version is incremented.

Thoughts?

@haacked commented on GitHub (Jul 2, 2013): Ok, so I just merged @EddieGarmon's change. But I kind of agree with you. Do we even need that phrase? It seems to me that it's obvious that other minor changes might be included with incompatible changes. Here's a couple of proposals. Would you mind sending a pull request with the one you like best? Here's what you wrote: > Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API. Patch and minor version MUST be reset to 0 when major version is incremented. And here's an alternative that might clarify a bit more what we mean. > Major version X (X.y.z | X > 0) MUST be incremented if a set of changes includes a backwards incompatible change to the public API. Patch and minor version MUST be reset to 0 when major version is incremented. Thoughts?

GiteaMirror commented

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

@ericdobson commented on GitHub (Jul 3, 2013):

I like it as is. It clearly and concisely states a very necessary element of the spec… how each higher level can include changes at lower levels. Minor version increments may include patch changes, and major increments may include both minor and patch. These facts must be stated clearly somewhere, and I don't see a more appropriate place for them than where they are now.

@ericdobson commented on GitHub (Jul 3, 2013): I like it as is. It clearly and concisely states a very necessary element of the spec… how each higher level can include changes at lower levels. Minor version increments may include patch changes, and major increments may include both minor and patch. These facts must be stated clearly somewhere, and I don't see a more appropriate place for them than where they are now.

GiteaMirror commented

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

@bessarabov commented on GitHub (Jul 3, 2013):

Ahh. At last I've understood the phrase It MAY include minor and patch level changes. (Witch now has a word also in it).

I was sure when I was reading semver spec and when I was asking this question that this phase concerns the change of numbers of semver but not the actual changes in the source code. But in fact this phrase means the changes in the source code.

I agree with @EricDobson that this statement should be written somewhere, but I think the current phrase should be changed to something simpler.

I like phrase proposed by @Haacked, but I don't like that the word "change"/"changes" is repeated twice in the sentence.

Major version X (X.y.z | X > 0) MUST be incremented if a set of changes includes a backwards incompatible change to the public API.

@bessarabov commented on GitHub (Jul 3, 2013): Ahh. At last I've understood the phrase `It MAY include minor and patch level changes.` (Witch now has a word `also` in it). I was sure when I was reading semver spec and when I was asking this question that this phase concerns the change of numbers of semver but not the actual changes in the source code. But in fact this phrase means the changes in the source code. I agree with @EricDobson that this statement should be written somewhere, but I think the current phrase should be changed to something simpler. I like phrase proposed by @Haacked, but I don't like that the word "change"/"changes" is repeated twice in the sentence. > Major version X (X.y.z | X > 0) MUST be incremented if a set of changes includes a backwards incompatible change to the public API.

GiteaMirror commented

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

@EddieGarmon commented on GitHub (Jul 3, 2013):

How about this option?

Major version X (X.y.z | X > 0) MUST be incremented if the set of all edits includes backwards incompatible changes to the public API. Patch and minor version MUST be reset to 0 when major version is incremented.

@EddieGarmon commented on GitHub (Jul 3, 2013): How about this option? > Major version X (X.y.z | X > 0) MUST be incremented if the set of all edits includes backwards incompatible changes to the public API. Patch and minor version MUST be reset to 0 when major version is incremented.

GiteaMirror commented

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

@bessarabov commented on GitHub (Jul 3, 2013):

Hm. I like it, but it is the first time we use the word 'edits'. I still think this is the best text that was proposed during this discussion, and we should use it.

@bessarabov commented on GitHub (Jul 3, 2013): Hm. I like it, but it is the first time we use the word 'edits'. I still think this is the best text that was proposed during this discussion, and we should use it.

GiteaMirror commented

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

@EddieGarmon commented on GitHub (Jul 3, 2013):

Another option could be to use the word 'modifications' instead of 'edits'.

@EddieGarmon commented on GitHub (Jul 3, 2013): Another option could be to use the word 'modifications' instead of 'edits'.

GiteaMirror commented

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

@Tieske commented on GitHub (Jul 3, 2013):

Feels like over engineering. Just the currently included also seems to do the job.

@Tieske commented on GitHub (Jul 3, 2013): Feels like over engineering. Just the currently included `also` seems to do the job.

GiteaMirror commented

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

@dwijnand commented on GitHub (Jul 5, 2013):

I don't like introducing new terminology like "modifications". I think the current version with "also" is good.

@dwijnand commented on GitHub (Jul 5, 2013): I don't like introducing new terminology like "modifications". I think the current version with "also" is good.

GiteaMirror commented

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

@bessarabov commented on GitHub (Jul 5, 2013):

@dwijnand, I agree with you that we should not add new terms. But the term 'modifications' are already used in semver:

3 ... Any modifications MUST be released as a new version.

Sorry, but I don't agree with you that the version with "also" is good. My idea why we should change it is described in this comment: https://github.com/mojombo/semver/issues/130#issuecomment-20410274

@bessarabov commented on GitHub (Jul 5, 2013): @dwijnand, I agree with you that we should not add new terms. But the term 'modifications' are already used in semver: > 3 ... Any modifications MUST be released as a new version. Sorry, but I don't agree with you that the version with "also" is good. My idea why we should change it is described in this comment: https://github.com/mojombo/semver/issues/130#issuecomment-20410274

GiteaMirror commented

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

@dwijnand commented on GitHub (Jul 5, 2013):

@bessarabov You're right, "modifications" has been used already.

In that respect there are:

2 "modified"
2 "modifications"
vs
22 "change"/"changes"

However, after re-reading your comment I finally understand how you misunderstood the spec. Perhaps there's still room for improvement (but I'm still not convinced by @Haacked'd proposed phrase).

@dwijnand commented on GitHub (Jul 5, 2013): @bessarabov You're right, "modifications" has been used already. In that respect there are: - 2 "modified" - 2 "modifications" vs - 22 "change"/"changes" However, after re-reading your comment I finally understand how you misunderstood the spec. Perhaps there's still room for improvement (but I'm still not convinced by @Haacked'd proposed phrase).

GiteaMirror commented

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

@bessarabov commented on GitHub (Jul 5, 2013):

@dwijnand I'm very glad that we have understood each other =)

Yes, I completely agree that there this phrase can be written better, but I can't write it better than it is now. And to make some progress on this issues I have created the pull request, because I still think that the phrase in pull request is better than we have now.

Maybe there should be glossary of the terms that used in semver, but it is different task from the task in this issue (and I think that the task to create glossary is huge).

@bessarabov commented on GitHub (Jul 5, 2013): @dwijnand I'm very glad that we have understood each other =) Yes, I completely agree that there this phrase can be written better, but I can't write it better than it is now. And to make some progress on this issues I have created the pull request, because I still think that the phrase in pull request is better than we have now. Maybe there should be glossary of the terms that used in semver, but it is different task from the task in this issue (and I think that the task to create glossary is huge).

GiteaMirror commented

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

@haacked commented on GitHub (Jul 5, 2013):

Let's move this discussion to the PR that @bessarabov created #133

@haacked commented on GitHub (Jul 5, 2013): Let's move this discussion to the PR that @bessarabov created #133

GiteaMirror referenced this issue

2026-02-17 12:17:40 -06:00

[PR #84] [CLOSED] Adds special identifiers #728

GiteaMirror referenced this issue

2026-04-16 11:00:17 -05:00

[PR #84] [CLOSED] Adds special identifiers #1595

GiteaMirror referenced this issue