mirror of
https://github.com/semver/semver.git
synced 2026-07-11 06:53:03 -05:00
[GH-ISSUE #1120] Proposed v2.0.1: BREAKING.ADDING.FIXING #1545
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: github-starred/semver#1545
Reference in New Issue
Block a user
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Originally created by @Incognito on GitHub (May 19, 2025).
Original GitHub issue: https://github.com/semver/semver/issues/1120
There's a lot of misuse or misunderstanding of SemVer in the wild. Common example we all experience: people break the public API but do not increment MAJOR.
I think a big part of this is that yes of course people are not reading the documentation, but we could dig a pit of success for these people to fall into instead of trying to teach them all how to use it correctly. Presently, the names of the numbers is closer in semantics to importance assigned to a number instead of semantics related to the change itself.
I propose that we rename these numbers in the docs to something semantically aligned with what an increment in the number does instead of what position it holds in the sequence.
There's a lot of room for wishy washy interpretations of what "major" and "minor" mean (especially for people who don't read the spec in detail, or lack experience to learn from someone who understands it). There is much less room for ad-hoc interpretation when they have something like "Breaking.Adding.Fixing" instead.
"This is the number I increase when it breaks someone who updates the package version".
"This is the number I increase when it fixes a bug but doesn't add a feature or break the API".
Etc.
Perhaps you disagree with the specific words in my proposal, if so, do you disagree with the general concept of renaming the concept in the docs too?
This change should be fully backwards compatible with the package ecosystem and (as I see it) does not "add a new feature".
If agreed I can submit the change request. I think this would make a gentle nudge on the global package ecosystem towards a slightly better better state.
@dunyakirkali commented on GitHub (May 19, 2025):
I like this idea
@zafarkhaja commented on GitHub (May 19, 2025):
Sure, better names won't hurt and might go a long way, but I believe coming up with something comprehensive will prove to be the biggest challenge. I know the proposed naming is just an example but to highlight the issue, under this scheme how does one identify the number to increment, let's say, for "deprecating" changes?
Just as an idea, what if we approach this from the opposite side, meaning not in terms of API changes but in terms of changes to client code that the API changes will entail should you decide to upgrade the dependency?
@Incognito commented on GitHub (May 19, 2025):
@zafarkhaja That's a really cool direction. Something like "BREAKS_API.EXTENDS_API.API_PRESERVING_FIX" is clear to the consumer of a package and the vendor too. I think it covers your deprecation case.
Not sure how you handle it but I like the method of: release a add_stuff with new features and tag methods deprecated. next version breaks_stuff and removes deprecated code. I think some people prefer to directly break_stuff (based on their support needs).
@zafarkhaja commented on GitHub (May 19, 2025):
With regard to deprecations, as per the current version of SemVer (p.7) "deprecating" changes lead to increments of the minor version which you call EXTENDS_API. Of course, it's a common practice to offer a replacement for a deprecated method but it's not always the case. Like in my situation where I realized that providing such functionality was incorrect to begin with, so I just deprecated the method without a replacement. But even with a replacement, in my opinion, it's still debatable whether providing a better alternative to a deprecated method could be considered as extension of the API or its improvement.
The point I was trying to make is that from the dependency's point of view the version numbers can be incremented for various reasons, sometimes unrelated to the API it provides. For instance, in the case of the minor version, the change could be a new API method, or it can be some sort of internal improvement like refactoring or performance optimization, or maybe even a major improvement to the API documentation which is shipped with the dependency (such as Javadoc). All this variety of reasons complicates the naming, as it's hard to find a descriptive name capable of exhaustively covering all possibilities.
On the other hand, from the dependent's point of view the possibilities are limited, you either will have to adjust your code or you won't. In the case of the latter possibility, the decision to upgrade is based on the preferability of the changes. So I was thinking that this limitedness of possibilities might simplify the naming.
@tanadedtk-eng commented on GitHub (Aug 26, 2025):
Ok
@horvathmilcsi commented on GitHub (Sep 25, 2025):
Very important proposal! "Major" and "Minor" simply not clear terms enough. Naming should be self explanatory. Thumbs up!
@ghost commented on GitHub (Dec 30, 2025):
https://github.com/semver/semver/issues/1120#issuecomment-3335947551
@jwdonahue commented on GitHub (Mar 13, 2026):
This has come up in the past:
Here's what the original author had to say on the topic:
https://github.com/semver/semver/issues/411#issuecomment-347050750
The MAJOR.MINOR.PATCH nomenclature, dates back to at least the 90's, probably earlier. It was a well known pattern, by the time @mojombo created the SemVer spec. There is nothing in the spec that says MAJOR is only for breaking changes. Likewise for MINOR and feature additions. You are free to bump any of them as you see fit.
@jwdonahue commented on GitHub (Mar 13, 2026):
Well it seems I also had something to say on this topic in the past:
https://github.com/semver/semver/issues/625#issuecomment-913860491
@jwdonahue commented on GitHub (Mar 13, 2026):
I also propsed HR.MR.LR for field labels, here, where:
HR == High Risk
MR == Medium Risk
LR == Low Risk
See the linked discussion.