Loosen "backwards incompatible API changes increment the major version" #442

New Issue

GiteaMirror · 2026-02-17T12:05:44-06:00

GiteaMirror commented

2026-02-17 12:05:44 -06:00

Originally created by @artgoldberg on GitHub (Nov 6, 2020).

The strict definition of major version in "backwards incompatible API changes increment the major version" and

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 also include minor and patch level changes. Patch and minor 
version MUST be reset to 0 when major version is incremented.

strikes me as overly strict. In particular, it does not explicitly allow the major version number to be incremented when major features that are not backwards incompatible are added to a system. For example, a software package might add a feature that speeds up execution by parallel execution. The API change that supports this feature might be an optional parameter to a run() method which controls whether parallel execution is used. Since the parameter is optional, this change is backward compatible.

Many other types of major features that are not backwards incompatible can be imagined.

Incrementing the major version in these situations can be warranted and attractive because major, new, backward compatible features can represent a major improvement in the functionality of a system.

This suggestion could be implemented by a simple change to 8:

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 also include minor and patch level changes. Patch and minor 
version MUST be reset to 0 when major version is incremented. **The Major version MAY be incremented
if major functional features that are not backwards incompatible are added.**

An example would be helpful too.

Originally created by @artgoldberg on GitHub (Nov 6, 2020). The strict definition of major version in "backwards incompatible API changes increment the major version" and 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 also include minor and patch level changes. Patch and minor version MUST be reset to 0 when major version is incremented. strikes me as overly strict. In particular, it does not explicitly allow the major version number to be incremented when major features that are not backwards incompatible are added to a system. For example, a software package might add a feature that speeds up execution by parallel execution. The API change that supports this feature might be an optional parameter to a run() method which controls whether parallel execution is used. Since the parameter is optional, this change is backward compatible. Many other types of major features that are not backwards incompatible can be imagined. Incrementing the major version in these situations can be warranted and attractive because major, new, backward compatible features can represent a major improvement in the functionality of a system. This suggestion could be implemented by a simple change to 8: 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 also include minor and patch level changes. Patch and minor version MUST be reset to 0 when major version is incremented. **The Major version MAY be incremented if major functional features that are not backwards incompatible are added.** An example would be helpful too.

GiteaMirror closed this issue

2026-02-17 12:05:45 -06:00

GiteaMirror commented

2026-02-17 12:05:46 -06:00

@ljharb commented on GitHub (Nov 6, 2020):

I don't think your added sentence is necessary, or an improvement. You can always do a major bump for whatever reason you want - but you should feel discouraged from doing so when there's non-breaking changes. "major functional features" isn't something semver cares about - either it's breaking (theoretically or in practice), and thus must be semver-major, or it's not, and should be semver-minor or semver-patch, but may be semver-major.

@ljharb commented on GitHub (Nov 6, 2020): I don't think your added sentence is necessary, or an improvement. You can always do a major bump for whatever reason you want - but you should feel discouraged from doing so when there's non-breaking changes. "major functional features" isn't something semver cares about - either it's breaking (theoretically or in practice), and thus must be semver-major, or it's not, and *should* be semver-minor or semver-patch, but *may* be semver-major.

GiteaMirror commented

2026-02-17 12:05:47 -06:00

@ljharb commented on GitHub (Nov 6, 2020):

In other words, "major" here means "breaking changes", not "arbitrarily and subjectively impactful or exciting".

@ljharb commented on GitHub (Nov 6, 2020): In other words, "major" here means "breaking changes", not "arbitrarily and subjectively impactful or exciting".

GiteaMirror commented

2026-02-17 12:05:48 -06:00

@artgoldberg commented on GitHub (Nov 6, 2020):

Could someone please add a "consensus seeking" label to this issue?

Thanks

@artgoldberg commented on GitHub (Nov 6, 2020): Could someone please add a "consensus seeking" label to this issue? Thanks

GiteaMirror commented

2026-02-17 12:05:48 -06:00

@Nixinova commented on GitHub (Jan 12, 2021):

The spec says nothing about not being able to increment arbitrarily, just that it must be incremented for breaking changes at least. I think the current wording is fine.

@Nixinova commented on GitHub (Jan 12, 2021): The spec says nothing about not being able to increment <major> arbitrarily, just that it must be incremented for breaking changes at least. I think the current wording is fine.

GiteaMirror commented

2026-02-17 12:05:48 -06:00

@artgoldberg commented on GitHub (Jan 12, 2021):

Following that logic, I would expect you to be arguing in favor removing It MAY also include minor and patch level changes.

Closing, as my idea hasn't found support, and I don't want to be bothered by it any more.

Thanks

@artgoldberg commented on GitHub (Jan 12, 2021): Following that logic, I would expect you to be arguing in favor removing `It MAY also include minor and patch level changes`. Closing, as my idea hasn't found support, and I don't want to be bothered by it any more. Thanks

GiteaMirror referenced this issue

2026-04-16 10:30:07 -05:00

[GH-ISSUE #442] Version incrementing with prerelease #1189

GiteaMirror referenced this issue

2026-04-20 09:57:33 -05:00

[GH-ISSUE #442] Version incrementing with prerelease #2056

GiteaMirror referenced this issue

2026-04-25 17:15:12 -05:00

[GH-ISSUE #442] Version incrementing with prerelease #3038

GiteaMirror referenced this issue

2026-06-13 12:48:18 -05:00

[GH-ISSUE #442] Version incrementing with prerelease #4567