mirror of
https://github.com/semver/semver.git
synced 2026-07-11 06:53:03 -05:00
[GH-ISSUE #411] Rename "Major" to Breaking and "Minor" to Feature #2038
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: github-starred/semver#2038
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 @gr2m on GitHub (Nov 21, 2017).
Original GitHub issue: https://github.com/semver/semver/issues/411
I’ve been thinking a lot about semantic versions as part of my work on semantic-release, which automates releases for Node projects based on commit conventions (#410).
"Major" and "Minor" has a risk of subjective assessment where there should be none. The definitions "version when you make incompatible API changes" for "Major" and "version when you add functionality in a backwards-compatible manner" for "Minor" are clear.
I think changing the wording from "Major version bump" to "Breaking version bump" and from "Minor version bump" to "Feature version bump" makes things much more clear and leaves no room for using version number for marketing purposes.
I’d be more than happy to send a pull request for this change if folks agree
Here from my latest talk at Node Interactive
@FichteFoll commented on GitHub (Nov 22, 2017):
Interesting idea. The only downside I see is that it one might think you can increase each of these independently and thus not consider resetting all lower parts to
0when releasing a new breaking version (I like how well that sounds compared to "major version").Well, and obviously the struggle against history.
@haacked commented on GitHub (Nov 22, 2017):
I love the idea, but this is the part that gives me pause. I often think of Semver as semantics applied to a version number. Major, Minor, and Patch are well understood when describing the form of a version. Then you apply Semver to give each of those parts meaning. It's a mapping of semantics to the corresponding version number part.
Perhaps BREAKING.FEATURE.PATCH makes for a good learning instrument.
The following is the preamble to Semver:
Maybe we change it to
Or something along those lines.
@gr2m commented on GitHub (Nov 22, 2017):
Isn’t
BREAKING.FEATURE.PATCHapplying a much clearer semantic thanMAJOR.MINOR.PATCH? I know that major/minor/patch is used in the past, but just because something always has been that way doesn’t mean we can’t change it :)From my own experience talking about this topic a lot, it’s rather "commonly misunderstood", which is why I bring up the issue
If semver.org would change their wording, it would go a long way. It would be a big step towards changing the convention of how we call the x.y.z version numbers.
@haacked commented on GitHub (Nov 22, 2017):
Yes.
My point is that MAJOR.MINOR.PATCH doesn't describe the semantics of a version number, it describes the form of the version number. Then Semver the spec describes the semantics applied to that form. I think that distinction is important.
That's good information.
I'll mull it over. I'd like to hear from more people. There may be a way we can keep the distinction and yet have
BREAKING.FEATURE.PATCHbe the predominant way we talk about it.Perhaps we could invert things. Make
BREAKING.FEATURE.PATCHthe dominant approach and have a footnote that it applies to versions that are commonly known asMAJOR.MINOR.PATCH.@jasonrhodes commented on GitHub (Nov 22, 2017):
Seems like "Breaking" / "Feature" / "Fix" is just one way to understand the major/minor/patch distinction, right? Someone could very easily decide to group together a bunch of interesting new features and release them all as a "new major version" and begin to ask their users to use the "new way of doing things" yet not have a single intentional breaking change in that release. Yet, as Ashley Williams (and others) has said, all fixes are breaking changes, so maybe it should be
BREAKING.FEATURE.BREAKING:D@Fishrock123 commented on GitHub (Nov 22, 2017):
Is not really at all useful.
A single number is all a machine would need so this is really about intent / as best as the author can tell to help inform downstream users (people) in a succinct and consistent way.
@coderbyheart commented on GitHub (Nov 22, 2017):
I agree that
MAJOR.MINOR.PATCHmerely serves as a helper to identify the individual numbers in the semver string and does not necessarily express semantics. The scope of the semver specification document is to define the rules.But the goal of the semver project is to make it easy "to communicate your intentions to the users of your software". Adopting the
BREAKING.FEATURE.PATCHnotion will support this goal by adding the way semver is intended to used in practice in a prominent place to the document.@frvge commented on GitHub (Nov 22, 2017):
What about MAJOR.BREAKING.FEATURE.PATCH ? MAJOR could be (ab)used for marketing and big new feature releases, which may include breaking changes, but don't have to, while the remaining parts are mostly technical. Or are we constrained by 3 levels?
@pdecat commented on GitHub (Nov 22, 2017):
Isn't the breaking already implicit, i.e.
MAJORBREAKING.MINORBREAKING.PATCHBREAKING?PS: https://xkcd.com/1172/
@StuartQ commented on GitHub (Nov 22, 2017):
This is a great idea. Actually semantic.
@silkentrance commented on GitHub (Nov 22, 2017):
MAJOR was always meant to be breaking. And while it may not break things, it will introduce major changes like for example a bunch of new features.
MINOR can also break stuff. And while it may not break things, it may introduce minor changes such as new features whilst still retaining backwards compatibility.
PATCH will fix things in the current MAJOR and MINOR and should not be breaking things.
What is so difficult about understanding such simple things?
Why not go along with the abstraction MAJOR.MINOR.PATCH. This has been a best practice for who knows how many years and even more mythical man months and even before the "inception" of Semver.
On my part I'd vote for closing this one for good. Lesson learned and hopefully understood. If not, why not introduce a sd-semver alternative where sd stands for star date as in Star Trek, overly redundant and artificial.
@young-steveo commented on GitHub (Nov 22, 2017):
I like
BREAKING.FEATURE.FIXprecisely because it is semantic. Until I had it memorized, I personally struggled to remember PATCH--erroneously calling it MINOR--because I would have a "minor fix" to a piece of code.@silkentrance commented on GitHub (Nov 22, 2017):
@young-steveo read carefully through https://github.com/semver/semver/issues/411#issuecomment-346485021
@silkentrance commented on GitHub (Nov 22, 2017):
@gr2m And while we are at it: BREAKING.FEATURE.FIX
BREAKING limits a new major release semantically to be breaking with existing stuff, which it may not.
FEATURE implies that the feature does not break with existing stuff, which it may.
FIX implies that, well, it is a fix for some problem and that it will not break anything, same as before.
Your proposal actually limits the expressiveness of Semver.
@young-steveo commented on GitHub (Nov 22, 2017):
Looking at just the words,
MAJOR does not imply breaking, even though breaking changes typically occur.
MINOR implies small or insignificant changes, though new features may be very big / significant.
PATCH implies... I dunno, the same thing as MINOR?
@Meligy commented on GitHub (Nov 22, 2017):
Same here.. you should be able to tell people to look at the spec https://semver.org/
Because the first you see there is the summary:
@Meligy commented on GitHub (Nov 22, 2017):
There's something interesting about https://github.com/semver/semver/issues/411#issuecomment-346485021, quoting:
This is not compatible with https://semver.org/, which says:
Note the
in a backwards-compatible mannerbit.@FichteFoll commented on GitHub (Nov 23, 2017):
Realistically speaking, we'd have a hard time trying to replace the long-standing
MAJOR.MINOR.PATCHcatch phrase (I'll just call it that way). I don't renaming these three as a viable change because it will inevitably cause a knee-jerk response my many not aquinted with the semantic meaning of these. @silkentrance already showed how misleading and imprecise the current terms are (no offense).However, I strongly believe that we can introdue an alternative spelling for the semver parts. We just add mentions of them in a couple places and maybe even default to them in the descriptive text (specification) after they are defined. Thinking of this:
So, in an figurative manner,
MAJOR.MINOR.PATCHbecomes the term for the visual representation of a three-part version number, whileBREAKING.FEATURE.FIXwill become the term for how semver defines this representation in its context. Does that make sense?@jasonrhodes commented on GitHub (Nov 23, 2017):
My point earlier was that if you intentionally break your API in a way that isn't a bugfix, semver says you should always bump the "major version". But it's never been clear to me that the inverse is true: that if you bump your major version, you must break your API. It doesn't seem helpful to change this language to be IMO too specific, especially when changing a convention like this will be incredibly difficult in the first place.
FWIW I don't agree that semver is simple for everyone to understand as-is. I'm just not sure if it's the release names that are causing the confusion, and I'm not convinced this change would be successful or that it would help much if it was.
@rk3rn3r commented on GitHub (Nov 23, 2017):
v1.593.0
"We never do BCs in our library and we are screwed now, because we are not allowed to increase the BREAKING number of the actual semver specification. Once we have been allowed to increase MAJOR on non-breaking but major (step) releases, but we stated at the beginning of our project to do SemVer, but since the rules changed, we regret it."
Just a thought from my point of view as a long time SemVer user that also introduced it at my company and advertises it all time. I would not like to come to that situation. It's even worse when you went until 7.2.0 and end up in 7.689.0 or something.
@xcambar commented on GitHub (Nov 23, 2017):
Any chance you'd like
BREAKING.NON_BREAKING.FIX?The point behind
NON_BREAKINGis in allowing a simpler, 2-digit versioning (ie with implicit rightmost.0, as in2.1, as you've guessed) that remains compatible with the full syntax, yet allows smaller/simpler project teams with less versioning discussions.I understand at length the utility of the 3 digits, but I've seen and worked on many small scale projects that would have been totally happy with only 2-digits.
Allowing this in the specs would open doors to developers less seasoned to versioning, and for this reason, it goes in the same direction as this discussion.
@alphapapa commented on GitHub (Nov 23, 2017):
It seems like that would be an alternative to SemVer, maybe "SemVer Lite" (dumb name but you get the idea). It would need to be emphasized very strongly that use of this system absolutely forbids breaking changes for any reason.
And, for that reason, I think it's probably not a good idea, because what project never wants or needs to make any breaking changes? Even security fixes can occasionally be breaking, e.g. when Python finally enabled SSL cert verification. If a project declared it would never make breaking changes, but then a few years later had to, what would it do, switch to "SemVer Classic" and likely break downstream packaging?
It's an interesting idea, but I think it would be best proposed as a completely alternative system to SemVer.
@xcambar commented on GitHub (Nov 23, 2017):
It's actually the opposite idea, sorry I didn't make it clear.
I suggested the following naming convention for the "complete" syntax:
BREAKING.NON_BREAKING.FIXThis allows to open SemVer up to the following (sub, compatible, simpler) syntax:
BREAKING.NON_BREAKING.So, to answer your concerns, it absolutely allows (and not
forbids) breaking changes.@ncoghlan commented on GitHub (Nov 23, 2017):
SemVer has always been about assisting users with risk management on upgrades rather than absolute assurances, and different projects assign different risk profiles to the MAJOR.MINOR.PATCH semantics across different aspects of their compatibility promises.
As an example of doing that more explicitly, SchemaVer is interesting, as it focuses specifically on data model compatibility, and the ability of old records to validate against the new schema: https://snowplowanalytics.com/blog/2014/05/13/introducing-schemaver-for-semantic-versioning-of-schemas/
There, the order is "Model-Revision-Addition" for "Most old data will fail validation", "Some old data fails validation", and "All old data still passes validation".
So rather than changing the terminology at the SemVer level, it may make sense to instead offer some guidance on choosing more opinionated aliases for the fields like "REMOVE.ADD.FIX" (talking about API evolution), "ADAPT.REBUILD.UPGRADE" (talking about a project like CPython that mostly preserves API compatibility in MINOR releases, but only preserves ABI compatibility at the PATCH release level), or the "BREAKING.FEATURE.FIX" suggested here.
@abatishchev commented on GitHub (Nov 24, 2017):
Please do not change. Update the documentation instead, make it clearer and richer. Software versioning isn't about breaking changes only, it's about new feature, major and minor. One may have no breaking changes but one hardly can have no new features. So needs (semantic) versioning still.
@rarkins commented on GitHub (Nov 24, 2017):
Package producer view:
PATCH = I fixed something
MINOR = I added something, maybe broke something
MAJOR = I definitely broke something
Package consumer view:
PATH = Should be fine to adapt without checking
MINOR = Read release notes to decide if it needs further checking
MAJOR = Verify we definitely don't have a problem with an of the noted breaking changes
I think that the biggest value semver can provide is to consumers of packages, not producers, and it's about assessment of risk. Any naming change or description change considered here should ideally encourage package producer behaviour to be more aligned with package consumer needs, i.e. conveying the risk of the upgrade.
Regardless of naming convention, the reality of open source is that few people have time to backport fixes to every minor release stream, so we all need to adopt "unneeded" feature releases in order to also keep up with patches now or in future. i.e. if you're on 2.x, you often can't hop off that train and need to take the instability ("maybe broke something") with the stability ("fixed something")
The addition of a feature in well-designed modular code could be far lower "risk" of accidental breakage of existing functionality than many complicated fixes are, e.g. fixes may cross many parts of existing code
A large refactor (e.g. jumping from node 4 to node 8 and replacing all callback-based code with async/await) could also be higher risk than the addition of a modular new feature
Major releases without breaking changes are nearly always vanity releases, and ideally semver discourages it if it is designed to benefit package consumers instead of producers
Exceptions can be for major releases of large refactors or features that cross a lot of code in less-modular codebases. I can forgive a package producer for humbly bumping major version because of stability doubts.
Something else that needs to become accepted is whether bumping major versions is considered undesirable or inevitable? e.g. lately there's been a lot of major version upgrades purely because of dropping support for node 4, and this can be expected yearly from now on, according to node's schedule. Is everyone fine with 1+ major releases per year for node.js packages?
@yann-yinn commented on GitHub (Nov 24, 2017):
Naming things is hard and "breaking", "feature" and "fix" naming is awesome : concise and explicit. You know exactly when you must update a number and which one; without even read the docs.
@rk3rn3r commented on GitHub (Nov 24, 2017):
@nyl-auster but the current meaning for MAJOR is, that it must be increased on a breaking change, but you can increase it, when you do a major release (for example releasing a bunch of new features, re-architecture or refactor release without any API break, etc.).
changing the definition to BREAKING.NON_BREAKING.FIX will drastically restrict the meaning of SemVer.
The current definition still allows everyone to use that "strict mode", but the stricter definition would not be compatible to the current implementation.
Probably that suggested BREAKING.... pattern can become an enhancement mode of SemVer like "SemVer Strict" (or SemVer 2.0.0 Strict hehe).
@yann-yinn commented on GitHub (Nov 24, 2017):
@rk3rn3r oh I see, so sometimes "MAJOR" means "NEW VERSION WITH LOTS OF NEW FEATURES BUT BACKWARDS COMPATIBILITY". And sometimes "NEW VERSION THAT WILL BREAK YOUR SITE"
Those are two different meanings that are associated with the first number, so the "semantic" part became somehow confusing, am i wrong ?
@rk3rn3r commented on GitHub (Nov 24, 2017):
@nyl-auster when I get point 8 on semver.org right:
You must increase on a breaking API change, but you can increase it when it (only) includes features and bugfixes. at least to my understanding.
@yann-yinn commented on GitHub (Nov 24, 2017):
@rk3rn3r i understand this point as :
"you must increment X as soon as there is a breaking change. If there is also a fix included at the same time,well, okay, it's fine, but still don't forget to reset minor and patch numbers"
@StuartQ commented on GitHub (Nov 24, 2017):
Bumping the MAJOR version just because it's a large release doesn't jibe with my reading of the definition of a MAJOR release.
It doesn't say "increment the MAJOR version when you make incompatible API changes, or when making compatible API changes, but you've made a subjective decision that it's a big release. I've read through the detailed specification and I can't see anything in there that says you MAY increment the MAJOR version. If the MAJOR version was to be used, then surely we'd have some like this:
But we don't, it only says that for the MINOR version.
Am I missing something that allows a MAJOR version to be non-breaking, other than that it's not explicitly forbidden?
@StuartQ commented on GitHub (Nov 24, 2017):
If that was the case, what would be the difference between MAJOR and MINOR?
@rk3rn3r commented on GitHub (Nov 24, 2017):
@StuartQ SemVer uses RFC2119 https://www.ietf.org/rfc/rfc2119.txt
point 8 is the main point about the major version and it only states that you MUST (you are forced to) increase MAJOR when you do breaking changes. It doesn't say anything that it is ONLY for breaking changes. Furthermore, on the contrary it states, that it MAY include features and bugfixes.
An increased MAJOR part, that only includes refactoring or new features and bugfixes, is not forbidden by strict logical interpretation imho.
Strictly logically I would say, that it is no MUST to increase the MAJOR part, when you do a big release that covers a development milestone without any breaking change (just refactoring or bunch new features), according to the RFC wording and the basic logical meaning, it's not forbidden to increase MAJOR version part and reset MINOR and PATCH in this and similar cases, according to the MAY clause.
@StuartQ commented on GitHub (Nov 24, 2017):
@rk3rn3r I see why that interpretation has been made now, thank you. I have always taken
to mean that when you are bumping the major version (because of incompatible API changes), you are permitted to also include features/bugfixes. It doesn't say:
In my reading, the MAY relates to inclusion of features and bugfixes in a MAJOR release, not the incrementing of the MAJOR release number. However, I can certainly see how it is being read that way.
Most importantly though, bumping the MAJOR number when there are incompatible API (I.e breaking) changes, seems to be an exact fit for a MINOR version. My favourite thing about semver is the removal of subjective judgements on whether a release is "big enough" for a major release or not. Allow an increase in the major number without breaking changes brings back that subjectivity for no apparent gain.
If anything, the debate around what the exact meaning of the MAJOR version number strengthens the case for this change. If the definition of MAJOR was tightened to be unambiguously for breaking changes then the clarity of semver will increase.
@rk3rn3r commented on GitHub (Nov 24, 2017):
@StuartQ I have seldom seen a big release that has no breaking API changes and doesn't break though. That's where I would decide to make it clear, that there was no INTENDED breaking change on the API, but the release change is probably so big (by changing internals, performance optimisations, refactoring etc), that I want it to be handled/seen like a breaking change and so I increase the MAJOR version.
And I guess, that is why the definition is exactly like it is in SemVer 2.0.0 (point 8). It states a pattern people used already before SemVer was created/defined and just formalized it. changing a MAJOR version part means: This version could break your app with a very high probabilty!
@Integralist commented on GitHub (Nov 26, 2017):
As mentioned by @jasonrhodes and others, MAJOR does not always mean "breaking" (I know it's spec'ed that way, but the way it has been used so far hasn't always followed that path).
I also agree with @Haacked in that we should keep what we have and let the spec define the semantics.
@mojombo commented on GitHub (Nov 27, 2017):
This is an interesting and enlightening discussion. I'll give you some insight into how I thought about these matters when I originally authored the spec.
Let's start with the MAJOR version number. I'll agree that there is some wiggle room for interpretation as stated, but I intended it to mean that if you break your API you MUST increment (which is obvious from the spec) but you MAY ALSO increment it in absence of any breaking changes if you want to communicate to the consumer that they should pay special attention to this release. As mentioned, this is perhaps because you did a large (non-breaking as far as you can tell) refactor to speed things up but so much has changed internally that you want to be cautious and make sure nobody auto-updates to this release without knowing it. Or maybe while the API is technically unbroken based on your previous documentation, you clarified some matters, made the code more strict, and can't guarantee that nobody was using it in a way that may have worked based on their interpretation of the ambiguous documentation. Or maybe you really do want to make a big marketing splash about some new game-changing set of features but would rather not arbitrarily break something in order to be allowed to bump the MAJOR version.
To me, a MAJOR version bump means "either I broke something or I really want you to pay attention." Frivolous use of a MAJOR version bump should be considered deplorable, but honestly, people are already so reticent to bump MAJOR that I doubt very much (nor have I seen evidence to suggest) that it will be much abused. In fact, I could argue that SemVer's main objective is to force you to bump MAJOR when you break your API. Everything else is a small detail in comparison.
Now, let's move on to the matter of naming the parts of the version. @Haacked was exactly correct when he said:
MAJOR.MINOR.PATCH is what the parts of the version number are called, based on their order of appearance. They represent an obvious hierarchy of importance based on their names (or at least one that is so prevalent as to be learned in short order by newcomers). When I say "MAJOR version bump", everyone in all the kingdoms of programming knows what I mean. If we start saying "BREAKING version bump", only eyebrows will be raised and quizzical looks encountered. The biggest part of why SemVer enjoyed any success at all was because it took something that already existed in the world, formalized it, and gave it a name. If you want to teach someone SemVer or are arguing about what SemVer means or how your project should apply it, I guarantee that you will naturally use MAJOR, MINOR, and PATCH in that discussion, because they refer to the various parts of the version number. That naming scheme already existed in the world and is very well understood and useful. The problem was, nobody agreed on exactly what each part of a version number meant. SemVer takes those names and applies formalized semantics so that when you do different things to those parts, you can effectively signal something reliable to the consumer.
I'm dubious that changing those names in the spec will help people better understand SemVer. In fact, it could lead to more confusion as to why we thought we had to come up with new names for something that is already well understood (i.e. which part of the version number is called what). That said, SemVer has a life of its own now, and nowhere more so than on npm, so maybe I'm missing something. @gr2m you said:
I'm curious what specifically you've encountered, and what misunderstandings you're talking about.
@jwdonahue commented on GitHub (Nov 27, 2017):
My initial take on this idea was cool, totally makes sense. I've been in the room when marketing wanted vNext, not a vPast.minor.patch, and I think I have an understanding of the tension between the engineer's need for exactitude and marketing's requirement for something eye catching and brief in the propaganda. Reading so many interesting points on this subject is awesome. After reading and thinking about it, I still prefer the Major.Minor.Patch abstraction combined with the current SemVer 2.0.0 semantic descriptions, but it's also obvious we need some additional guidance in the document. Perhaps what we need is to require that anyone claiming SemVer compliance, include some SemVer.Meta data indicating their exact semantics? That would have to include prerelease and build meta tag semantics as well.
The document doesn't cover any of the common naming conventions for versioned artifacts, and those also provide semantic meaning in practice. I like the fact that SemVer is not cluttered with these extraneous details, but I think they should be codified somewhere and interlinked with SemVer. Maybe SemVer.Meta is really something that should be embedded in one of these outer scopes where it can indicate or link to producer process conventions?
@silkentrance commented on GitHub (Nov 27, 2017):
@mojombo please include the digested information of https://github.com/semver/semver/issues/411#issuecomment-347050750 in the specification. peeps somehow seem to need it otherwise they'd go rampant especially the followers of @gr2m.
and perhaps you might want https://github.com/semver/semver/issues/411#issuecomment-346485021 as a guide for making this crisp and clean 😀
@silkentrance commented on GitHub (Nov 27, 2017):
@FichteFoll no offence taken. open discussion is good. And I must strongly object monty python-ishly to you objecting my objection. In fact, even minor versions, i.e. FEATURE versions may introduce breaking changes to the system. And if you are in my world, we are talking alpha versions of components of new major releases that introduce new features that are currently under development.
And while these components are still under development, the main software release, which composes these components into a singular release or distribution package, makes use of these interim component releases. Very similar to what is called a SNAPSHOT release in maven terms, or pre releases in SEMVER terms.
As such a breaking minor release from a component may break with other components in the same system, needing the other components of the same system to adopt to these changes.
That being said, SEMVER should accept breaking changes on all levels, as every release will eventually be breaking something, even PATCH level releases.
@silkentrance commented on GitHub (Nov 27, 2017):
And I would also like https://github.com/semver/semver/issues/410#issuecomment-347151258 to chime in.
@naderman commented on GitHub (Nov 29, 2017):
In my experience the most common misunderstanding from novice users who usually have not actually read the semver spec is thinking that there are "minor" API BC breaks which do not require incrementing the MAJOR version. In fact due to the marketing value of version numbers I've encountered even very experienced developers who are so afraid of incrementing the MAJOR number that they'll take pretty much any excuse to delcare a breaking change MINOR.
Renaming the first number in the version to BREAKING would make it clearer to these people that any breaking change requires this number be incremented. However I agree that it would take a very long time for this change in naming to become a common explanation of version numbers for newcomers. I'm not sure it would help to add this to the semver spec, when the hope is to get more people who never read the spec to apply it correctly.
@jwdonahue commented on GitHub (Jul 12, 2018):
So I think the consensus here is that the proposed changes will not substantially improve the spec and are unlikely to be taken if a PR is presented. @gr2m, if you don't intend to push this further along, could you please close it?
@davidbarratt commented on GitHub (Mar 7, 2022):
Interesting, I didn't know about this issue, but I came to the exact same conclusion as the author #625