mirror of
https://github.com/semver/semver.git
synced 2026-07-11 04:52:47 -05:00
[GH-ISSUE #703] Community driven RFC? #3191
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: github-starred/semver#3191
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 @alexandrtovmach on GitHub (May 14, 2021).
Original GitHub issue: https://github.com/semver/semver/issues/703
Originally assigned to: @alexandrtovmach on GitHub.
Hey there 👋,
Some time ago I've become a maintainer of this repo to help with resolving contributions. In result, we have cleaned up issues/PRs boards, and most of the things that I can handle already resolved. But a big part of issues/PRs is actually discussions about updates to specification. I committed myself for resolving simple things:
Any problems?
I'm not ready to take responsibility to merge any of the changes to
masterand publish it to live website as v2, 3, 4 etc. As not the original author of this spec I haven't enough majority to make decisions like this 🤷♂️. Original maintainers not actively participate in discussions about next versions of SemVer, but it doesn't mean that community effort should be just ignored.What to do?
I'd propose to make a sub version of SemVer, and publish it as "Community Driven RFC". That's the place where I think we can make decisions together, about what should be published and what's not. Simple voting system with emojis in discussions will help on it. For example:
I understand that spec updates it's not something that should happen every day, but we need somehow handle community feedback on it, and right now I don't see any other way for it. Would like to hear any ideas about that in comments
Thanks 😉
cc: @anangaur @dherman @indirect @isaacs @segiddins @steveklabnik @ljharb
@steveklabnik commented on GitHub (May 14, 2021):
Personally, I see our responsibility as maintainers of the spec as being to clarify where implementations that are used in the wild diverge from the spec, and fix those things. The largest thing here is the ranges proposal, because that is a huge aspect of these systems in practice that is not in the specification itself.
Major changes to the semver spec shouldn't happen at this point, in my opinion, people who want to make significant breaking changes to the spec should fork it into some other versioning scheme.
@ljharb commented on GitHub (May 14, 2021):
I can't agree with this harder; semver is what it is, and if people want something different, they should feel free to go make something different.
@alexandrtovmach commented on GitHub (May 14, 2021):
Okay, does it mean we should just answer to any proposed changes like:
"spec is something stable, and if you want to update it, please create fork"
?
@mentalisttraceur commented on GitHub (May 14, 2021):
Re: "SemVer is what it is, everything else should be a fork".
I don't know if you guys heard, but if you want to lock in a stable version of something as-it-is, while still leaving room for new different things under the same umbrella, there's this cool versioning scheme that's really good for that called SemVer which the SemVer spec is already using to version itself.
Put another way, there is no such thing as just "SemVer". There is SemVer 2.0.0 (and a few earlier SemVer releases). SemVer 2.0.0 "is what it is", and it always will remain SemVer 2.0.0. Releasing SemVer 2.0.1 or SemVer 2.1.0 or SemVer 3.0.0 won't take SemVer 2.0.0 away from anyone.
I mean sure, you can say "we're never releasing another SemVer, ever (at least until further notice)" and tell people to make a fork for every new suggested improvement. But this is the natural place for coordination. "Make a fork" is a great way to fragment the community of people interested in making something that's almost SemVer 2.0.0, but a little better. And if despite that eventually someone comes up with a sufficiently better fork, then if you don't bless it as SemVer x.y.z, people will start calling it that anyway.
Best case scenario, either SemVer 2.0.0 is "good enough" so no fork ever outcompetes it and when I say "SemVer" people know I mean this one, or another fork is so much better that it wins and when I say "SemVer" everyone knows I mean that fork (except when I specify SemVer 2.0.0 or lower, everyone knows I'm talking about the versions of SemVer that were maintained here).
But the uncomfortably likely scenario is that one or more forks are just good enough that it gets some adoption but it never stops being ambiguous which one people mean, or some fork is strictly better but not enough for humanity to switch while you're sitting on the "official" name and version.
@mentalisttraceur commented on GitHub (May 14, 2021):
I suggest you simultaneously
@mentalisttraceur commented on GitHub (May 14, 2021):
You are in the best position publish SemVer 2.0.1-proposal1 or SemVer 2.1.0-proposal1 or SemVer 3.0.0-proposal1.
And you can - I presume - make it so that on the website 2.0.0 continues to be the main one which people get when they hit the website without specifying a version.
Given the massive adoption SemVer enjoys, you would immediately get feedback if you did that. If it messes up anything for anyone, people will tell you. And you haven't actually broken anything for anyone or committed to anything or trapped yourself in a corner by doing so, because that's just publishing a pre-release of another SemVer spec.
Then you can actually look at complaints.
The complaints that come down to "this is different than what I'm used to, I don't like it" or "I think this is adding extra stuff which I don't want people who use my version numbers to worry about" can be answered with "then just specify in your project that you're using SemVer 2.0.0 or SemVer 2.0 or SemVer 2”.
Which of course everyone should already be doing! In every one of my projects with a version number I say "this uses SemVer version 2", and I'm sure everyone who really groks SemVer is nodding along as I say this.
And then once you've filtered that out, the rest of the objections have actual "logical shape" which we can deal with as programmers. Like
@mentalisttraceur commented on GitHub (May 14, 2021):
For the record, here are the only four very tiny proposals I would make:
Three patch-level SemVer spec update proposals
(In your shoes I would publish these as separate SemVer
2.0.1-proposal1.*versions, and see if anyone raises any good argument that these are more than simply "bug fixes" - clarifications of what the rules already do or don't imply. These might not need to modify the formal spec text or the formal grammar text - it might be possible to put them in the FAQ or Introduction sections, although I worry about people missing them in the FAQ because the misunderstandings they address come more from the way human intuition interacts with the spec text.)(
2.0.1-proposal1.metadata) Add a sentence explicitly clarifying that although build metadata (the+part) does not effect precedence within SemVer, packages and tools are allowed to specify additional precedence rules beyond SemVer by which packages that differ only by build metadata can be sorted.It is a common point of confusion. I think SemVer was never intended to disallow packaging systems from meaningfully sorting by something in addition to the public interface changes that SemVer cares about. In fact I think the overwhelmingly common reason to have build metadata is to allow versioning information which someone or something uses for some kind of sorting, just not sorting that SemVer cares about. And I've seen actual popular packaging systems in the wild avoid showing new uploads to users as upgrades if only the build metadata changed. I've seen projects get stuck trying to figure out how to use SemVer for releases which don't change the API, because they feel like they're not allowed to use the build metadata to indicate non-API-effecting significant updates.
Could maybe go in the FAQ, although I feel that in the spec, right next to where it says that the build metadata is ignored for precedence, is the best place for it. This is the kind of thing that you'll see formal standards documents clarify sometimes, within the spec itself, precisely because this misinterpretation is common.
(
2.0.1-proposal1.limitations) Add a sentence explicitly saying that packaging systems should probably not limit their allowed version strings and precedence rules to just SemVer without additions, because SemVer is limited to describing public interface compatibility, and most packaging systems and packages in them actually have further considerations which are important in those contexts.This is the misunderstanding which makes some packaging systems actively require SemVer and only SemVer. This is also the misunderstanding that prevents even some projects which aren't hogtied by such packaging systems from using SemVer as part of a richer versioning scheme. This is the misunderstanding that made so many people ask "how do we use SemVer nightly/automated builds?"
Probably belongs in the introduction. That is probably the right place to intercept people who end up thinking "we're going to cram everything into SemVer, we don't need anything else", square-per-round-hole style.
(
2.0.1-proposal1.prereleases) Add a section explicitly clarifying that since pre-releases have none of the compatibility guarantees, you are allowed to use pre-release versions for various builds where you don't know for sure what the compatibility is (like automated nightlies).Optionally, this can explicitly describe the following community conventions which have developed, in an informative and explicitly not normative way, and that they are all compatible with existing SemVer rules:
0.0.0-*pre-releases.Again, this would just be acknowledging that all three of these are compatible with SemVer 2.0.0 - this would not be saying that you must or should do any particular approach. That's why this is a patch-level change - it's clarifying something which is already allowed but which a lot of people find not obvious.
This could just go in the FAQ, because it literally is a frequently asked question.
One major-level SemVer spec update proposal
(For most purposes this is a backwards-compatible change, but it is the curse of SemVer that it requires some extremely non-disruptive changes to be major bumps.)
(In your shoes I would publish this as SemVer
3.0.0-proposal1.multi, while heavily emphasizing just how very similar and compatible it is, and see if anyone has an objection which amounts to "wait! if you do this, it makes SemVer unusable/broken!")Allow the build metadata part of the SemVer to contain more
-and+characters. No semantics are changed: the build metadata is still ignored for sorting purposes at the SemVer level.Formally, a tiny change to the Backus-Naur grammar definition:
<dot-separated build identifiers>becomes<dot-or-dash-or-plus-separated build identifiers>, and it's definition is changed so that-and+are also allowed as a separator like.is.Notably, this is only a breaking change in that new version numbers will be considered invalid by existing parsers which are strict about the contents of build metadata. It also means that people who want to parse assumed-valid SemVer numbers can't do it with logic like "split on all instances of
-(or+), but we're just going to assume there's only two parts" (which is bad coding practice, and every language I know of also makes it just as easy to split a string on just the first occurence of something rather than all occurences).Notably, this is a backwards-compatible change in every other way. All version strings which are valid under SemVer 2.0.0 remain valid, and mean the same thing.
But surprise, with this tiny change, build metadata can look like a whole 'nother SemVer, which can have a build metadata which looks like yet another SemVer, and so on. SemVer 3.0.0 doesn't care if it does or not. But this little tiny bit of extra freedom enables tooling on top of plain SemVer which understands multiple SemVer versions combined into one version string. I think people could build a lot on top of that. Maybe even anything worth building, without ever needing any other changes to the SemVer spec itself. But right now the one little restriction of not being able to have any more
-or+in the build metadata really ties the hands of any version scheme which wants to be usable inside package systems which enforce SemVer. But if the SemVer project officially published just the tiny update to allow those two characters in the build metadata, all the package systems and parsing libraries would probably follow, because it's such a tiny and harmless and easy-to-implement change. And then it would probably empower a lot.@mentalisttraceur commented on GitHub (May 15, 2021):
Maybe I'll draft each of these proposals as PRs this weekend, especially if anyone actually expresses interest, especially especially if someone who has the ability tells me they'd pin the PR or issue for them to encourage community discussion.
I think SemVer and other things building on top of it would greatly benefit from any and all of them. I don't think they are disruptive, and I think they make enough sense that each one could get majority support behind them.
@alexandrtovmach commented on GitHub (May 17, 2021):
Basically all what you said, it's something that I have in my mind, but... again I can't move forward with any updates without original maintainers approve 🤷♂️
I also think if something keeps in open source repo, it expected to be supported and modified by community.
@indirect commented on GitHub (May 17, 2021):
If you think SemVer should be changed, this is the wrong repo for that. This repo does not exist to tell the existing package managers how to do things. It exists to document what they are already doing.
If we are missing something about how npm, pip, rubygems, nuget, cocoapods, cargo, etc, are already using SemVer, adding or correcting that is a good PR. If you want to change this repo in a way that does not match what package managers are already doing, we will (politely) decline your PR because it does not match the goals of this repo.
I hope that helps clarify 👍🏻
@alexandrtovmach commented on GitHub (May 17, 2021):
@indirect Yeah, now it's more clear for me 👍
@indirect commented on GitHub (May 17, 2021):
@alexandrtovmach great, and thanks again for all your help maintaining!