Feedback: what semver is _not_ for (semver is not for Products) #234

New Issue

GiteaMirror · 2026-02-17T11:38:13-06:00

GiteaMirror commented

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

Originally created by @GreenAsJade on GitHub (Jul 9, 2016).

At semver.org it asked for feedback here.

What I would like to request is that you include a paragraph that describes what semver is not designed for.

Because semver is clearly designed for clear versioning of software modules (and most specifically the APIs to those).

It's really not designed for versioning products.

The problem with using it for versioning products, is that product versions have to communicate not only (and often not all) API change, but rather feature sets.

A number of times now I've had to work with groups who think that because you use semver for software packages, it's a great idea to use it for products.

It is not.

The classic sort of problems are:

1.5.0 of a product will typically be a planned release after 1.4.0. So what should be the version of the first feature update release after 1.4.0? It can't be 1.4.1, because it is not a patch: it does bring new features.

Similarly, 2.0.0 of a product is often driven more by licensing/billing changes than backwards compatibility or not.

If you could point this out in the doc, it'd save "Product Owners" a lot of arguments :)

Thanks,

Martin

Originally created by @GreenAsJade on GitHub (Jul 9, 2016). At semver.org it asked for feedback here. What I would like to request is that you include a paragraph that describes what semver is _not_ designed for. Because semver is clearly designed for clear versioning of software modules (and most specifically the APIs to those). It's really not designed for versioning products. The problem with using it for versioning products, is that product versions have to communicate not only (and often not all) API change, but rather feature sets. A number of times now I've had to work with groups who think that because you use semver for software packages, it's a great idea to use it for products. It is not. The classic sort of problems are: 1.5.0 of a product will typically be a planned release after 1.4.0. So what should be the version of the first feature update release after 1.4.0? It can't be 1.4.1, because it is not a patch: it does bring new features. Similarly, 2.0.0 of a product is often driven more by licensing/billing changes than backwards compatibility or not. If you could point this out in the doc, it'd save "Product Owners" a lot of arguments :) Thanks, Martin

GiteaMirror added the consensus seeking question labels 2026-02-17 11:38:13 -06:00

GiteaMirror commented

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

@wawiesel commented on GitHub (Jul 11, 2016):

Great points Martin. I wish your title was something like "SemVer does not work for Products" so I didn't have to get lucky to get here. :) Like many software development groups, we have a large product that is composed of many software modules. I am pushing hard for the modules themselves to adopt SemVer, but for the overall product, I really can't see how we could use it.

Our product is a nuclear reactor simulation framework, and breaking backwards compatibility for us would be if a user's "input file" (the text input which defines the model and drives the simulation) from a previous version no longer worked. We intend that this never happens, so if we used SemVer for the product, we would be on like version 1.24 and it just isn't really conveying as much to the user anymore. They want to know how much better/faster, what new capabilities does it have, and 6.1-->6.2 indicates "some" whereas 6.2-->7.0 indicates "a lot". And for us it is not really a difference between 6.2 and 7.0 but a difference between 6.0 and 7.0 that we are looking at to decide what is "a lot", i.e. "how far have we come since the last major version update"?

So add my "progress" metric to your "billing" and "licensing" metric and we have three things that go in to a product version, or ProdVer. :)

ProdVer

Major
- user must apply for new license + pay full cost recovery fee
- product delivered as stand-alone installer
- considered a "big update" since the last major version
Minor
- user must apply for new license + pay reduced cost recovery fee
- product delivered as "upgrade" to Major.Minor-1
- considered a "small update" since the last minor version
Patch
- patch delivered as "upgrade" to specific Major.Minor.Patch-1
- considered an incremental bug fix since last patch

Of course, the license could be implicit and the fee=0, but I think this could be a workable "definition".

"ProdVer" is for people! "SemVer" is for systems!

@wawiesel commented on GitHub (Jul 11, 2016): Great points Martin. I wish your title was something like "SemVer does not work for Products" so I didn't have to get lucky to get here. :) Like many software development groups, we have a large product that is composed of many software modules. I am pushing hard for the modules themselves to adopt SemVer, but for the overall product, I really can't see how we could use it. Our product is a nuclear reactor simulation framework, and breaking backwards compatibility for us would be if a user's "input file" (the text input which defines the model and drives the simulation) from a previous version no longer worked. We intend that this never happens, so if we used SemVer for the product, we would be on like version 1.24 and it just isn't really conveying as much to the user anymore. They want to know how much better/faster, what new capabilities does it have, and 6.1-->6.2 indicates "some" whereas 6.2-->7.0 indicates "a lot". And for us it is not really a difference between 6.2 and 7.0 but a difference between 6.0 and 7.0 that we are looking at to decide what is "a lot", i.e. "how far have we come since the last major version update"? So add my "progress" metric to your "billing" and "licensing" metric and we have three things that go in to a product version, or ProdVer. :) ### ProdVer - Major - user must apply for new license + pay full cost recovery fee - product delivered as stand-alone installer - considered a "big update" since the last major version - Minor - user must apply for new license + pay reduced cost recovery fee - product delivered as "upgrade" to Major.Minor-1 - considered a "small update" since the last minor version - Patch - patch delivered as "upgrade" to specific Major.Minor.Patch-1 - considered an incremental bug fix since last patch Of course, the license could be implicit and the fee=0, but I think this could be a workable "definition". "ProdVer" is for people! "SemVer" is for systems!

GiteaMirror commented

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

@GreenAsJade commented on GitHub (Jul 13, 2016):

Thanks for taking the time to consider & respond.

I like the way you've gone with "ProdVer".

I'm not sure, yet, whether it's possible to find a good "standard" for ProdVer in the same way that there is one for SemVer, because of the less technical more marketting/client side to it.

For example, in my experience the different categories are

You (the user) have to buy a new license: "major". Not often, please.
- A big update. Users likely perceive it as "visibly different"
You (the user) welcome this release: "minor". Often, please, but not too often.
- A feature set, or a broad new feature (eg "Android support" or "that reactor shutdown sequence you've been waiting for"): "minor"
You (the user) just expect these, and don't really care, other than that they happen when they need to: "patch"
- Bug fix. Incremental feature addition.

But this is driven by the market/sales models I've been involved with.

@GreenAsJade commented on GitHub (Jul 13, 2016): Thanks for taking the time to consider & respond. I like the way you've gone with "ProdVer". I'm not sure, yet, whether it's possible to find a good "standard" for ProdVer in the same way that there is one for SemVer, because of the less technical more marketting/client side to it. For example, in my experience the different categories are - You (the user) have to buy a new license: "major". Not often, please. - A big update. Users likely perceive it as "visibly different" - You (the user) welcome this release: "minor". Often, please, but not too often. - A feature set, or a broad new feature (eg "Android support" or "that reactor shutdown sequence you've been waiting for"): "minor" - You (the user) just expect these, and don't really care, other than that they happen when they need to: "patch" - Bug fix. Incremental feature addition. But this is driven by the market/sales models I've been involved with.

GiteaMirror commented

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

@emperorz commented on GitHub (Oct 23, 2016):

It's for public API's. Have you changed the API?

@emperorz commented on GitHub (Oct 23, 2016): It's for public API's. Have you changed the API?

GiteaMirror commented

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

@FranklinYu commented on GitHub (Feb 17, 2017):

@emperorz They are talking about applications that have no API, such as a mobile application on Android/iOS. If you define "API" as "the way user touches" then it is very difficult to define "compatibility".

@FranklinYu commented on GitHub (Feb 17, 2017): @emperorz They are talking about applications that have no API, such as a mobile application on Android/iOS. If you define "API" as "the way user touches" then it is very difficult to define "compatibility".

GiteaMirror commented

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

@jeme commented on GitHub (Mar 20, 2017):

IMO whenever you choose to use something you should evaluate weather or not it suits your purpose/needs.

I don't see any difference in the case of SemVer, if it suits your needs then use it, otherwise don't, I don't see any benefits for the spec here to make judgement on where it is useful to you or not, especially because others may disagree in that conclusion.

I think it's especially important to realize that the term "Product" can cover so many things, and for a subset of those SemVer might actually make perfect sense (we are not to judge)...

As for banding/marketing... there is plenty of examples that that is separate from the actual "Product" version, again... Find the approach that suits your need.

@jeme commented on GitHub (Mar 20, 2017): IMO whenever you choose to use something you should evaluate weather or not it suits your purpose/needs. I don't see any difference in the case of SemVer, if it suits your needs then use it, otherwise don't, I don't see any benefits for the spec here to make judgement on where it is useful to you or not, especially because others may disagree in that conclusion. I think it's especially important to realize that the term "Product" can cover so many things, and for a subset of those SemVer might actually make perfect sense (we are not to judge)... As for banding/marketing... there is plenty of examples that that is separate from the actual "Product" version, again... Find the approach that suits your need.

GiteaMirror commented

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

@yegeniy commented on GitHub (Apr 10, 2017):

@GreenAsJade - I use "semver" for product releases, but they are almost always minor releases (1.4.0 -> 1.5.0). The only time an increment to the patch comes about is in the rare and unexpected case of a "hotfix". These days, in all but the most legacy, monolithic projects, creating a new minor release is just as easy as creating a hotfix, so even hotfixes end up going out as minor releases.

I have a hunch that, unless you are leveraging release candidates, you should not assign a version number to a feature set until it is ready to be released. Most teams constrained to releasing "batches/sets of features" use a separate branch that's usually called develop to hold the next batch of features.

As for cases where semver matters to a product, they do exist, but even then, maintaining versioning semantics is less rigid than for APIs:

If the breaking change is to the Product itself (such as an undesirable button that gets removed), then that's usually just a MINOR version change.
If there's a breaking change to the product's API (its programmatic interface), then one can argue that it's best to release both the API and the product as a new MAJOR version, but that's a subjective call, since a product sometimes encompasses many APIs and usually no one cares about the semantic versioning of your product, until you are maintaining several versions of it

For an example where semver matters in a product, check out GitHub Enterprise, which in March was maintaining patches for five minor versions of its Product at once: https://enterprise.github.com/releases/ (even here, it's arguable that small breaking changes to the product are ushered in as minor changes).

@yegeniy commented on GitHub (Apr 10, 2017): @GreenAsJade - I use "semver" for product releases, but they are almost always minor releases (`1.4.0` -> `1.5.0`). The only time an increment to the patch comes about is in the rare and unexpected case of a "hotfix". These days, in all but the most legacy, monolithic projects, creating a new minor release is just as easy as creating a hotfix, so even hotfixes end up going out as minor releases. I have a hunch that, unless you are leveraging release candidates, you should not assign a version number to a feature set until it is ready to be released. Most teams constrained to releasing "batches/sets of features" use a separate branch that's usually called `develop` to hold the next batch of features. As for cases where semver matters to a product, they do exist, but even then, maintaining versioning semantics is less rigid than for APIs: * If the breaking change is to the Product itself (such as an undesirable button that gets removed), then that's usually just a MINOR version change. * If there's a breaking change to the product's API (its programmatic interface), then one can argue that it's best to release both the API and the product as a new MAJOR version, but that's a subjective call, since a product sometimes encompasses many APIs and usually no one cares about the semantic versioning of your product, until you are maintaining several versions of it For an example where semver matters in a product, check out GitHub Enterprise, which in March was maintaining patches for five **minor** versions of its Product at once: https://enterprise.github.com/releases/ (even here, it's arguable that small breaking changes to the product are ushered in as minor changes).

GiteaMirror commented

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

@grv87 commented on GitHub (Apr 9, 2019):

+1 for what semver is _not_ for.

Looking how many issues are opened about adding 4th number in version, leading (#507) or trailing (#391, #213, #332 etc.), I see that people want to use semver to solve all their problems.
Semver itself became so popular, and people just don't know and don't look for other approaches.
I've ever seen package managers or build tools that require semver strictly.

While it is amazing, Semver doesn't fit everywhere and for everybody.
Particularly, it doesn't fit:

when the version number is preassigned (or should be known) before an actual release
when a project wants to have version of some other project in its own version, like Sass in #200, Debian packages in https://github.com/semver/semver.org/issues/44#issuecomment-2251399 or versions of translations of Semver itself in https://github.com/semver/semver/issues/407#issuecomment-443499361

If the project/team can use Semver - they should.
For all others the website and repo should have the big warning when (why?) they SHOULD NOT use semver. This should scare away some people.
Semver owners and maintainers must be tired to answer the same questions again and again.

@grv87 commented on GitHub (Apr 9, 2019): +1 for `what semver is _not_ for`. Looking how many issues are opened about adding 4th number in version, leading (#507) or trailing (#391, #213, #332 etc.), I see that people want to use semver to solve all their problems. Semver itself became so popular, and people just don't know and don't look for other approaches. I've ever seen package managers or build tools that require semver strictly. While it is amazing, Semver doesn't fit everywhere and for everybody. Particularly, it doesn't fit: * when the version number is preassigned (or should be known) before an actual release * when a project wants to have version of some other project in its own version, like Sass in #200, Debian packages in https://github.com/semver/semver.org/issues/44#issuecomment-2251399 or versions of translations of Semver itself in https://github.com/semver/semver/issues/407#issuecomment-443499361 If the project/team can use Semver - they should. For all others the website and repo should have the big warning when (why?) they SHOULD NOT use semver. This should scare away some people. Semver owners and maintainers must be tired to answer the same questions again and again.

GiteaMirror commented

2026-02-17 11:38:21 -06:00

@alexandrtovmach commented on GitHub (Jun 10, 2020):

Thanks everyone for contributions, you're amazing 🎆 Did you find any consensus?

@alexandrtovmach commented on GitHub (Jun 10, 2020): Thanks everyone for contributions, you're amazing :fireworks: Did you find any consensus?

GiteaMirror commented

2026-02-17 11:38:22 -06:00

@mentalisttraceur commented on GitHub (Jun 11, 2020):

I think the last section of my comment on #519 about allowing combining multiple SemVers into one version string, would go a long way towards addressing many of those usecases @grv87 linked to.

Having said that, I agree with the general gist here: people are trying to stretch SemVer to cover everything, and one side effect of that mentality is that people and package systems are moving to rigidly limit versioning to only SemVer, and that doesn't work in many cases.

Semver should be one tool in our versioning toolkit. Even my "multiple SemVers" idea should maybe be a separate specification building on top of SemVer rather than part of SemVer itself.

@mentalisttraceur commented on GitHub (Jun 11, 2020): I think the last section of [my comment on #519](https://github.com/semver/semver/pull/519#issuecomment-642887824) about allowing combining multiple SemVers into one version string, would go a long way towards addressing many of those usecases @grv87 linked to. Having said that, I agree with the general gist here: people are trying to stretch SemVer to cover everything, and one side effect of that mentality is that people and package systems are moving to rigidly limit versioning to only SemVer, and that doesn't work in many cases. Semver should be one tool in our versioning toolkit. Even my "multiple SemVers" idea should maybe be a separate specification building on top of SemVer rather than part of SemVer itself.

GiteaMirror commented

2026-02-17 11:38:23 -06:00

@mk-pmb commented on GitHub (Oct 26, 2020):

I have a strong feeling that from SemVer's popularity arises an obligation to remind people that no matter how shiny your hammer is, some problems are better solved using other tools. Also I have a feeling that there's a limit for how big a project can become while adhering to SemVer, and if a project becomes too big (e.g. most magically-does-ALL-the-things frameworks), it needs to switch to some other versioning scheme.

@mk-pmb commented on GitHub (Oct 26, 2020): I have a strong feeling that from SemVer's popularity arises an obligation to remind people that no matter how shiny your hammer is, some problems are better solved using other tools. Also I have a feeling that there's a limit for how big a project can become while adhering to SemVer, and if a project becomes too big (e.g. most magically-does-ALL-the-things frameworks), it needs to switch to some other versioning scheme.

GiteaMirror commented

2026-02-17 11:38:25 -06:00

@ghost commented on GitHub (Sep 18, 2021):

Post-release subpatch versioning is a big reason why this doesn't work for products.

@ghost commented on GitHub (Sep 18, 2021): Post-release subpatch versioning is a big reason why this doesn't work for products.

GiteaMirror referenced this issue

2026-02-17 12:18:42 -06:00

[PR #234] [MERGED] Address "v" prefixing in the FAQ #775

Sign in to join this conversation.