mirror of
https://github.com/semver/semver.git
synced 2026-07-11 04:52:47 -05:00
[GH-ISSUE #461] Quick, easy-to-read description of semver etiquette for npm, etc. #4580
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: github-starred/semver#4580
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 @brody2consult on GitHub (Sep 4, 2018).
Original GitHub issue: https://github.com/semver/semver/issues/461
From https://github.com/mhevery/jasmine-node/issues/433 @ljharb and I encountered an all-to-often problem where package owners would publish breaking changes without updating the major version. This behavior leads to issues in downstream dependents at unpredictable points of time.
I would like to see a quick, easy-to-read description of npm semver etiquette that we can point some less experienced maintainers to.
I would be happy to contribute a draft at some point.
@jwdonahue commented on GitHub (Sep 25, 2018):
You may find some usable material in [my answer[(https://github.com/semver/semver/issues/462#issuecomment-423857465) to #462.
@jwdonahue commented on GitHub (Sep 25, 2018):
On second thought, I think you should encourage the NPM team to include this documentation. Tool specific etiquette is not the province of the SemVer spec.
@ljharb commented on GitHub (Sep 25, 2018):
I don't see how this behavior is tool-specific - if you remove the word "npm" in the OP it still applies the same.
@brody2consult commented on GitHub (Sep 25, 2018):
https://github.com/semver/semver/issues/462#issuecomment-423857465
I just raised https://npm.community/t/semver-etiquette-not-clear-enough/2380.
I just edited the title to be less npm-specific.
@jwdonahue commented on GitHub (Sep 25, 2018):
I think a careful read of the spec indicates that SemVer is meant to be applied to what it refers to as an "API". There are some other threads that drone on regarding the dichotomy between package and API. I have frequently argued that the spec is fine as-is, because it's not too constraining and that gives tool/ecosystem designers some maneuverability. If what you are versioning is your API, then SemVer is being applied to nodes in the dependency graph, not segments thereof. If what you are versioning is a package, then you have some tool/ecosystem issues to take into consideration.
I for one, believe that a package that defines any dependencies, is not an API package, it's an implementation. So now you could go down the versions of implementations per versions of API rabbit hole and learn the lesson of exponential complexity, or you can simplify around the versioned set; where set is a package of API('s), implementations and declared dependencies (part of the package interface).
The spec was deliberately left open to some interpretation. Tool ecosystem developers must make some choices and document their expected or discovered best practices. A package feed API that allows clients to flag/block packages with breaking changes relative to the client's current environment, is the tip of an different ecosystem than one that does not. On which side should the spec fall?
SemVer's simplicity has led to wide-spread adoption, and given tool makers considerable freedom to build their own ecosystems, both large and small. Probably none of them can be shown to adhere to a strict interpretation of the spec, primarily because its not possible to strictly interpret the spec. We must then turn to the specific tool/ecosystem developers and users for best practices within their domains. SemVer can't be responsible for those.
I have been working off-and-on, on a pair of related projects to try and provide a possible next step in the evolution of semantic versioning. Please have a look at VesionMeta and VersionSchema.
@alexandrtovmach commented on GitHub (Jun 10, 2020):
@brodybits Closed as answered, if you still have any questions ― feel free to re-open
@ljharb @jwdonahue Thanks for answers