[GH-ISSUE #444] SemVer declares API changes, but not the minimal required platform/engine/environment/framework #2057

New Issue

GiteaMirror · 2026-04-20T09:57:46-05:00

GiteaMirror commented

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

Originally created by @koresar on GitHub (May 16, 2018).
Original GitHub issue: https://github.com/semver/semver/issues/444

Please take a look at this issue: https://github.com/request/request/issues/2772#issuecomment-330948055

TL;DR version:

API did not change, so the software was releasing only the MINOR versions.
The software minimal required platform (in this case node.js engine version) did change from 0.10, to 4, to 6.
As the result the software could not be run on the unsupported platforms (node.js v0.10, v4, v6). It crashes production servers at runtime for many people out there causing revenue loss.

General best practice in node.js community:

Increase the MAJOR version when your software minimal platform version increases.
(E.g. if minimum supported node.js increases from v4 to v6 you bump from v2.86 to v3.0.)

The above mentioned issue practice:

Follow SemVer. Meaning: no API changes -> MINOR version upgrade.

Proposal:

Either mention that "bumping the minimal required platform should be considered a MAJOR release". Or
"bumping minimal required platform should not increase the software MAJOR version".

Please note, this is a serious issue. Please, avoid platform-specific holy wars. Let's improve SemVer even further.

Originally created by @koresar on GitHub (May 16, 2018). Original GitHub issue: https://github.com/semver/semver/issues/444 Please take a look at this issue: https://github.com/request/request/issues/2772#issuecomment-330948055 TL;DR version: * API did not change, so the software was releasing only the MINOR versions. * The software minimal required platform (in this case node.js engine version) did change from 0.10, to 4, to 6. * As the result the software could not be run on the unsupported platforms (node.js v0.10, v4, v6). It crashes production servers at runtime for many people out there causing revenue loss. ----- General best practice in node.js community: * Increase the MAJOR version when your software minimal platform version increases. (E.g. if minimum supported node.js increases from v4 to v6 you bump from v2.86 to v3.0.) The above mentioned issue practice: * Follow SemVer. Meaning: no API changes -> MINOR version upgrade. ----- Proposal: * Either mention that "bumping the minimal required platform should be considered a MAJOR release". Or * "bumping minimal required platform should not increase the software MAJOR version". ----- Please note, this is a serious issue. Please, avoid platform-specific holy wars. Let's improve SemVer even further.

GiteaMirror added the waiting for PR label 2026-04-20 09:57:46 -05:00

GiteaMirror commented

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

@jwdonahue commented on GitHub (Jul 12, 2018):

The spec is very clear that any breaking changes, which would obviously include breaking changes in dependencies, require a major version bump. If some organizations are failing to adhere to the semver guidelines, stop using their products or treat all of their releases as breaking changes.

The world is full of stupid developers and managers who will not get the message, no matter how many times you say it. The best solution to the problem referenced in your issue link is to do everything in your power to get the idiots fired ASAP, and I don't just mean the folks who ignore the SemVer spec and NPM guidelines when they publish, I mean the morons who allowed that laps of judgement to cost everyone so much money.

Auto-updating a production system from untested sources is at best, stupid, and criminally negligent in the worst cases. No amount of documentation is going to stop the criminally negligent from doing harm. Hell, even if you get them fired, they're likely to get drunk and kill somebody on the way home.

Since NPM is fairly node specific, and this particular issue seems extremely common to node.js, perhaps someone should add some static analysis to NPM to try and prevent packages from being published that violate the rules.

I have long lamented the lack of best practices documentation on this site. I even started up the wiki at one point, but that was taken away. I would be very much in favor of adding some very prominent language to the spec that included some pointers to well written guidelines in general as well as technology specific docs, but I don't think we can entertain adding one language/tool-chain specific do/don't to the spec for every use-case without rendering it incomprehensible.

@koresar, unless you intend to provide a PR for whatever intended changes you have in mind, please close this issue at your earliest possible convenience.

@jwdonahue commented on GitHub (Jul 12, 2018): The spec is very clear that any breaking changes, which would obviously include breaking changes in dependencies, require a major version bump. If some organizations are failing to adhere to the semver guidelines, stop using their products or treat all of their releases as breaking changes. The world is full of stupid developers and managers who will not get the message, no matter how many times you say it. The best solution to the problem referenced in your issue link is to do everything in your power to get the idiots fired ASAP, and I don't just mean the folks who ignore the SemVer spec and NPM guidelines when they publish, I mean the morons who allowed that laps of judgement to cost everyone so much money. Auto-updating a production system from untested sources is at best, stupid, and criminally negligent in the worst cases. No amount of documentation is going to stop the criminally negligent from doing harm. Hell, even if you get them fired, they're likely to get drunk and kill somebody on the way home. Since NPM is fairly node specific, and this particular issue seems extremely common to node.js, perhaps someone should add some static analysis to NPM to try and prevent packages from being published that violate the rules. I have long lamented the lack of best practices documentation on this site. I even started up the wiki at one point, but that was taken away. I would be very much in favor of adding some very prominent language to the spec that included some pointers to well written guidelines in general as well as technology specific docs, but I don't think we can entertain adding one language/tool-chain specific do/don't to the spec for every use-case without rendering it incomprehensible. @koresar, unless you intend to provide a PR for whatever intended changes you have in mind, please close this issue at your earliest possible convenience.

GiteaMirror commented

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

@koresar commented on GitHub (Jul 12, 2018):

I'd love to submit a PR. Please, give me few days. Thank you

@koresar commented on GitHub (Jul 12, 2018): I'd love to submit a PR. Please, give me few days. Thank you

GiteaMirror commented

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

@jwdonahue commented on GitHub (Jul 12, 2018):

No rush, I am just trying keep the issue list down to a manageable size with actionable items that are reasonably likely to be followed through on.

Thanks!

@jwdonahue commented on GitHub (Jul 12, 2018): No rush, I am just trying keep the issue list down to a manageable size with actionable items that are reasonably likely to be followed through on. Thanks!

GiteaMirror commented

2026-04-20 09:58:05 -05:00

@koresar commented on GitHub (Jul 29, 2018):

PR #452 submitted. I'm not quite happy with what I came up with though...

@koresar commented on GitHub (Jul 29, 2018): PR #452 submitted. I'm not quite happy with what I came up with though...

GiteaMirror commented

2026-04-20 09:58:06 -05: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-04-20 09:58:08 -05:00

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

The consensus is on the linked #546 PR.

@koresar commented on GitHub (Jun 10, 2020): The consensus is on the linked #546 PR.

GiteaMirror commented

2026-04-20 09:58:09 -05:00

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

@koresar okay, makes sense

@alexandrtovmach commented on GitHub (Jun 11, 2020): @koresar okay, makes sense

GiteaMirror commented

2026-04-20 09:58:10 -05:00

@cronvel commented on GitHub (Feb 20, 2021):

I ran into this recently and some users of my lib are complaining about a engine change on a semver MINOR.

I opened a question on Stack Overflow and asked Twitter about that. Isaac, author of the Node.js semver package and founder of npm answered this:

I've always considered SemVer Major to mean "you will have to change something on your end to start using this update".

If the previous version worked on platform version X, and the new version requires platform version X+n, then that qualifies, yes.

At the moment there is no resource on that matter found in search engine except this issue.
I think the SemVer spec should address this as soon as possible, because at the moment, it tells everyone that only API changes matter.

More specifically, for Node.js, this means that one would have to check ALL engine requirement for ALL dependencies, and I can't find a npm command for that.

@cronvel commented on GitHub (Feb 20, 2021): I ran into this recently and [some users of my lib](https://github.com/cronvel/terminal-kit/issues/156) are complaining about a engine change on a semver MINOR. I opened [a question on Stack Overflow](https://stackoverflow.com/questions/66282951/semver-policy-with-node-js-engine-enforcing/66289428#66289428) and asked Twitter about that. Isaac, author of the Node.js *semver* package and founder of *npm* answered this: > I've always considered SemVer Major to mean "you will have to change something on your end to start using this update". > > If the previous version worked on platform version X, and the new version requires platform version X+n, then that qualifies, yes. At the moment there is no resource on that matter found in search engine except this issue. I think the SemVer spec should address this as soon as possible, because at the moment, it tells everyone that **only API changes matter**. More specifically, for Node.js, this means that one would have to check ALL engine requirement for ALL dependencies, and I can't find a *npm* command for that.

GiteaMirror commented

2026-04-20 09:58:11 -05:00

@ljharb commented on GitHub (Feb 20, 2021):

Required engine support is part of your api.

@cronvel for npm, you can check precisely that with npx ls-engines.

@ljharb commented on GitHub (Feb 20, 2021): Required engine support *is* part of your api. @cronvel for npm, you can check precisely that with `npx ls-engines`.

GiteaMirror commented

2026-04-20 09:58:11 -05:00

@cronvel commented on GitHub (Feb 20, 2021):

@ljharb Maybe, but it's still need to be explicitly said by the doc, or at least in the FAQ.

More specifically, this section is very ambiguous to that respect:

What should I do if I update my own dependencies without changing the public API?

That would be considered compatible since it does not affect the public API. Software that explicitly depends on the same dependencies as your package should have their own dependency specifications and the author will notice any conflicts. Determining whether the change is a patch level or minor level modification depends on whether you updated your dependencies in order to fix a bug or introduce new functionality. I would usually expect additional code for the latter instance, in which case it’s obviously a minor level increment.

Since there is nothing about the engine, one may think of engine as a dependency.

@cronvel commented on GitHub (Feb 20, 2021): @ljharb Maybe, but it's still need to be explicitly said by the doc, or at least in the FAQ. More specifically, [this section](https://semver.org/spec/v2.0.0.html#what-should-i-do-if-i-update-my-own-dependencies-without-changing-the-public-api) is very ambiguous to that respect: > What should I do if I update my own dependencies without changing the public API? > > That would be considered **compatible since it does not affect the public API**. Software that explicitly depends on the same dependencies as your package should have their own dependency specifications and the author will notice any conflicts. Determining whether the change is a patch level or minor level modification depends on whether you updated your dependencies in order to fix a bug or introduce new functionality. I would usually expect additional code for the latter instance, in which case it’s obviously a minor level increment. Since there is nothing about the *engine*, one may think of *engine* as a dependency.

GiteaMirror commented

2026-04-20 09:58:12 -05:00

@ljharb commented on GitHub (Feb 20, 2021):

An implicit dependency is part of your api, since it’s something a user has to know to use your interface. The term “API” is ambiguous, but there’s no common sense interpretation of it that excludes platform support.

@ljharb commented on GitHub (Feb 20, 2021): An implicit dependency is part of your api, since it’s something a user has to know to use your interface. The term “API” is ambiguous, but there’s no common sense interpretation of it that excludes platform support.

GiteaMirror commented

2026-04-20 09:58:12 -05:00

@cronvel commented on GitHub (Feb 21, 2021):

@ljharb Still, some dumb peoples like me may lack some common sense, and need to be explicitly told things ;)

@cronvel commented on GitHub (Feb 21, 2021): @ljharb Still, some dumb peoples like me may lack some common sense, and need to be explicitly told things ;)

GiteaMirror commented

2026-04-20 09:58:13 -05:00

@koresar commented on GitHub (Feb 26, 2021):

An implicit dependency is part of your api

@ljharb that's what most people think. But could you please read the link I provided in the very beginning of this issue? https://github.com/request/request/issues/2772#issuecomment-330948055

That's the place which caused a lot of trouble. A lot.
Those people think different than most. They DON'T think that implicit dependency is the part of your api. They don't have the same "common sense" as you do. People are different. That's why there must be no ambiguous wording in any specification. Including SemVer.

@koresar commented on GitHub (Feb 26, 2021): > An implicit dependency is part of your api @ljharb that's what most people think. But could you please read the link I provided in the very beginning of this issue? https://github.com/request/request/issues/2772#issuecomment-330948055 That's the place which caused a lot of trouble. A lot. Those people think different than most. **They DON'T think that implicit dependency is the part of your api.** They don't have the same "common sense" as you do. People are different. That's why there must be no ambiguous wording in any specification. Including SemVer.

GiteaMirror commented

2026-04-20 09:58:14 -05:00

@ljharb commented on GitHub (Feb 26, 2021):

@koresar A developer with that stance is not going to be swayed by any content of any specification. They are not interested in preventing breakage, they are interested in using new features faster.

@ljharb commented on GitHub (Feb 26, 2021): @koresar A developer with that stance is not going to be swayed by any content of any specification. They are not interested in preventing breakage, they are interested in using new features faster.

GiteaMirror commented

2026-04-20 09:58:14 -05:00

@pboling commented on GitHub (Apr 4, 2025):

@ljharb Considering the potential impact of a gap in language understanding among English speakers with different levels of fluency, I think it would be kind to those who are looking for additional clarification to have it stated in the FAQ that platform support is "obviously and objectively" (to quote you, elsewhere) included within the existing spec's "API" terminology.

The levels of misunderstanding here are not entirely due to people wanting to release faster, or recklessly, but sometimes it may be a simple language-based misunderstanding of the spec, and those developers might be reformed if they had clear guidance from the spec or the official FAQ.

Over time it would bend the arc of usage toward more compliance. The very clear statements buried in the issue tracker are never going to rise to a level of exposure that could have a similar effect.

@pboling commented on GitHub (Apr 4, 2025): @ljharb Considering the potential impact of a gap in language understanding among English speakers with different levels of fluency, I think it would be _kind_ to those who are looking for additional clarification to have it stated in the FAQ that platform support is "obviously and objectively" (to quote you, elsewhere) included within the existing spec's "API" terminology. The levels of misunderstanding here are not entirely due to people wanting to release faster, or recklessly, but sometimes it may be a simple language-based misunderstanding of the spec, and those developers might be reformed if they had clear guidance from the spec or the official FAQ. Over time it would bend the arc of usage toward more compliance. The very clear statements buried in the issue tracker are never going to rise to a level of exposure that could have a similar effect.

GiteaMirror commented

2026-04-20 09:58:15 -05:00

@ljharb commented on GitHub (Apr 5, 2025):

@pboling when it's a language barrier i'm fully in support of things like a FAQ to add clarity.

@ljharb commented on GitHub (Apr 5, 2025): @pboling when it's a language barrier i'm fully in support of things like a FAQ to add clarity.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/semver#2057