mirror of
https://github.com/semver/semver.git
synced 2026-07-11 03:53:53 -05:00
[GH-ISSUE #237] Optional minor and patch versions #5279
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: github-starred/semver#5279
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 @zafarkhaja on GitHub (Dec 10, 2014).
Original GitHub issue: https://github.com/semver/semver/issues/237
The spec and the BNF grammar require that
but it's very common to omit minor and patch versions if they're
0. For example, many who think they follow SemVer write1instead of1.0.0or1.2instead of1.2.0, which is wrong according to SemVer.Should the spec be less strict on the normal version form? In other words, should the short form be qualified as a valid SemVer version?
@FichteFoll commented on GitHub (Dec 10, 2014):
Honestly, no. It's a good thing that all semantic versions have to follow this pattern for a few reasons:
1.2and1.3and the like you might even forget that you could actually add a patch version1.2followed by1.2.1is confusing and unnecessary.1or1.2likely don't even know about semver (hence the divergence). While semver does not restrict you from not using patch, these people will likely not follow the restrictions semver sets on updating a certain version number and assuming they do is definitely the wrong call.MAJOR.MINOR.PATCHyou can easily tell thatMAJOR.MINORis not a semver.@DavidFichtmueller commented on GitHub (Dec 10, 2014):
I am also against the optional minor and patch versions. Besides the already mentioned reasons, I also think that versions numbers in the form of
1and1.2also have their place within the semantic versions context, but they do have a different meaning than1.0.0or1.2.0.For instance if you describe something general/conceptional like the general data model or a processing pipeline of your application, you could say that this is for version
1(regardless of the minor and patch versions). Any substantial changes to the data model (or processing pipeline) would require a new major version. However something more specific, like your API documentation would only be valid for a specific minor version, like1.2. If patch versions have an influence on the output of a specific function this could additionally be noted in the API documentation (e.g. a certain edge case now returns an error code instead of throwing an exception) but the general statements are valid for all patch versions of this minor version.So to summarize:
MAJORversion numbers (1) if you want to say something that is true for all associated minor and patch versionsMAJOR.MINORversion numbers (1.2) if you want to say something that is true for all associated patch versionsMAJOR.MINOR.PATCHversions (1.2.0) if you want to reference a specific (semver valid) version.@FichteFoll commented on GitHub (Dec 10, 2014):
@DavidFichtmueller, your concern rather fits with the idea of #205 and not exactly the versions themselves.
@zafarkhaja commented on GitHub (Dec 10, 2014):
@FichteFoll while I tend to mostly agree with you I wouldn't be that adamant about some of your points.
0versions really makes it confusing?Having said that, I believe you've got a point.
@DavidFichtmueller the use cases you pointed out are widely used in package managers for the SemVer ranges/expressions, although in a slightly different way: when the actual minor or patch version isn't important you would put
*instead of it (1.2.*), whereas1.2would be identical to1.2.0.So again, I changed the title of the issue so that it's clear I'm not proposing to change the spec but rather to discuss the matter in order to see what community thinks of it.
The reason why I brought up this discussion is because I'm in the process of refactoring my version and expression parsers where I want to avoid code duplication in the following scenarios
Here, two different parsers are involved that have almost identical pieces of code for version parsing which I'd like to eliminate as it feels like duplication.
I think there's more to it. When we proceed to defining a BNF grammar for the SemVer ranges/expressions we would end up with two different sets of rules for the same concept of version because ranges/expressions do allow the short form.
So the question still remains. Is it a good idea to have same grammar rules applied to versions when parsing a single SemVer version and a whole SemVer expression? What are other pros and cons?
@bobthecow commented on GitHub (Dec 14, 2014):
👍 I'm with @FichteFoll on all counts.
@bperrybap commented on GitHub (Apr 7, 2015):
To me this is more of a parsing issue than a real issue.
Why not allow and accept and support version numbers of any of the 3 forms:
X
X.Y
X.Y.Z
for maximum compatibility and to increase adoption?
X is still the major number, Y is still the minor number, and Z is still the point number.
The rule would be that when a number is omitted it is zero from a semver version perspective
So
X is the same as X.0.0
X.Y is the same as X.Y.0
That way shorter revisions numbers can be specified but expand to the proper semver numbers
after being parsed.
This also helps future proof the scheme by allowing it to be extended in the future, say to include other extensions.
@FichteFoll commented on GitHub (Apr 8, 2015):
Same issue and problems as before. I also don't see how this would make SemVer more future proof that it is now.
@bperrybap commented on GitHub (May 9, 2015):
The reason it future proofs things is that it allows an arbitrary number of versioning digits. And that is what people will need to handle in their parsers.
So for example, you are currently mandating a very rigid maj.min.point system.
There is no need to be so strict with the numbering system and it locks you into this without any ability to extend in the future.
What is more important than a rigid format is to define how parsing should work.
And if defined properly, an arbitrary system can be used and yet still be compatible the current recommend numbering system.
i.e. users should be allowed to use what I described above
X
X.Y
X.Y.Z
and if the semver system expects X.Y.Z and only X is specified then X.0.0 would be used (Y and Z were not specified and so default to zero) and it all works.
Likewise if in the future you decide that X.Y.Z is not good enough and need to add another field, then currently the entire world breaks since if you go to X.Y.Z.A then it would mandate that X.Y.Z is invalid.
However, if you defined it such that missing fields are zero, then the old revisions still work rather than break.
Also, by having a less rigid system you could instantly move to X.Y.Z.A to be compatible with those that want to use a build number along with the version information. Those that don't want or need a build number could simply leave it off and it would default to zero and perhaps even be hidden.
I don't see the value of having such a rigid system when a less rigid system can be made to work and provides additional functionality as well as future proofing for further extensions.
@crazedsanity commented on GitHub (May 12, 2015):
While I agree with most of the reasonings that @FichteFoll has given, @bperrybap really has provided an excellent reason as well. I personally think it would be better to allow for the less rigid forms, though I think it is still better to prefer explicit over implicit.
@icorderi commented on GitHub (Jul 7, 2016):
Parsing versions with a missing patch number seems to be a recurrent request.
We can all agree that a complete version is formed by
X.Y.Z-pre+build.We can also agree that a release version with no build metadata is
X.Y.Z.What people are asking is the ability to accept a new release "X.Y" as
X.Y.0.A lot of libraries refuse to parse the convenient "X.Y", and they do rightfully so, because the spec says the version must have
X.Y.Z.I totally agree that a version is
X.Y.Z, but that should not mean that we can't allow a "X.Y" (string) to be parsed as a valid semver toX.Y.0.I believe that adding an extra item on the spec clarifying that a version "X.Y" with no patch information can be accepted as version
X.Y.0would benefit the semver spec. BothX.YandX.Y.0mean that there is no patch.@bperrybap commented on GitHub (Jul 7, 2016):
@icorderi,
be prepared to lose this battle. The ones that control semver seem to be very stubborn in their rigid ways.
To me any good system has mechanisms to be flexible. And a way to do this is to define rigid rules of how to deal with formats when they are not the preferred format rather than just take the rigid simple-minded approach of just rejecting anything that is not in the preferred format.
i.e. be very strict/rigid about how to handle less conformant formats than be so strict about enforcing a rigid format.
Also, it isn't just about having support for just X.Y, vs X.Y.Z the issues with semver go much deeper.
In fact, another area that is not handled by semver is pre vs post release versions or experimental development releases.
i.e. there is no way to have a semver version number that indicates that the release is a temporary developmental or experimental release that is post a given release and yet before the next official release number is known.
There has been lots of discussion on this including many valid scenarios as to why this is an important thing to support and that many other versioning systems can handle this while semver can not.
semver has taken a very limited view on the use of versioning information to the point of it only working for "real" releases, or near final releases leading up to a final "real" release like alpha, beta, release candidate etc... Anything else outside of that use is simply not handled/supported.
This is part of what creates all the craziness over release ZERO.
I finally gave up on trying to get semver updated to be better.
The biggest revelation I had was that you don't have to live with semver for your internal versioning.
All you have to do is map your revision numbering to something that works with semver rather than try to fix semver.
Once you accept that there will be a mapping between your revisions and semver strings, some of the semver limitations will evaporate.
So to deal with the silly X.Y.Z semver mandate just slam the .0 on the end if it isn't there.
i.e. map your s/w version to a semver version.
My solution to live within the semver restrictions is to create semver version strings by "abusing" the naming system and slamming stuff into the pre-release and metadata area.
By doing this it is possible to create post release versions before the next "real" release version is known.
While to semver these post release development versions will look like pre-release versions, so semver will favor the "real" releases over the non development/experimental release, which is actually what is desired.
In some environments the user can still have the opportunity to select and use the experimental release versions so it all works out quite well.
I believe that versioning needs to be very much automated.
So I created a semver version creation script that will create semver compliant version numbers directly from git information.
It does this by using the output from: git describe --dirty
and then massaging the output to form a semver compliant version.
It will parse the output string and convert it into a semver string.
So for example, if you have a tag of "v1.2rc1" you end up with a semver string of 1.2.0-rc2
There are several period, dash, and string manipulation rules & translations involved but it works great and can live within the semver restrictions.
In fact, for development releases, before you even tag the next pre-release or create the final release it works for that too as git describe includes additional information that can be put into the pre-release & meta-data fields.
So for example, say you did a commit after you just created a release and just need to get a quick semver development revision string without re tagging or even picking the next revision number. That can be done and the generated semver release version will contain the git information. The generated semver version "abuses" the semver spec by creating a "fake" pre-release version by using a dash after the most recent "real" version number.
So one commit after a v1.0 tag you would end up with semver release string of:
1.0.0-1-gd4ca264
This is done because the semver spec has no way to indicate a temporary post release development version that is a lower priority than the "real" release.
It is done this way to intentionally trick semver into thinking the release is a pre-release version so the "real" release version will have precedence over this development release.
i.e. the 1.0.0 release will have precedence over the post release of 1.0.0-1-gd4ca264 or any other post 1.0.0 release until the next tag containing the revision number for the next "real" release is done.
The key to this is to abuse the fact that semver use the dash to signify a lower priority release.
So instead of thinking of the dash as a "pre-release" signifier just think of it as a way to indicate that the release is a lower priority than the "real" release.
While some may cry fowl over using semver versions this way, the version strings being created are still semver compliant.
To me at this point it becomes a game of how to abuse the semver spec rules to give revisions that provide what you want & need while still living within the naming, parsing, and priority rules.
The best thing I ever did was create a way to automate creating semver version strings directly from the git repository.
@FichteFoll commented on GitHub (Jul 7, 2016):
As you rightfully pointed out, @bperrybap, SemVer is primarily intended for public releases, and it does its job rather well I'd say. Unfortunately it does not tailor anything that would help in the develop process. There has been a lot of discussion about this in https://github.com/mojombo/semver/issues/200 2 years ago, which I highly recommend to read if you're interested in this. Personally, I am undecided whether SemVer should support the post-release versioning of if that is something that should be handled by a SemVer fork. I do agree that a unified versioning system for these workflows would be useful, though.
Regarding the exact issue at hand (allowing to omit the patch or minor version), I listed some arguments against this proposal in my initial post, which still hold and are the reason why this particular proposal will most likely not be accepted.
@bperrybap commented on GitHub (Jul 7, 2016):
@FichteFoll
I've read #200 as well as a slew of other discussions that occasionally seemed to get spirited/heated.
Even participated in a few.
The constant drumb beat of "You must be doing something wrong, if you can't operate using semver version strings" has gotten very old.
And that is what has lead me to, for the most part, ignore it all and simply figure out a way to/create semver compliant version strings when required that can trick semver into behaving the way I need it to behave.
(There are many ways to abuse the semver naming rules to get the desired behavior you would like)
While I do still consider semver a bit broken and overly unnecessarily rigid,
I think from a broader perspective, semver would greatly benefit from a white paper style write up that shows how semver can be used with different development and versioning methodologies and also provide some automation version scripts to do things like create semver version strings from git information or other versioning information.
consider it like a reverse parser.
It takes version string input and hacks it up into a semver compliant string.
Like I said earlier the greatest thing for me was to stop worrying about semver and simply use a tool that can create a semver compliant version string whenever it was required and not attempt to ever use semver for the actual project versioning.
This also allows a project to be built for different environments that may have different versioning requirements.
@icorderi commented on GitHub (Jul 11, 2016):
Seems there is a lot of history going on around.
@bperrybap I can see your frustration, but lets try to keep this discussion narrowed to optional patches (or implicit patch 0). One battle at a time.
@FichteFoll
I read your arguments against lowering the patch requirement to optional. I'll have to disagree with you.
Not with the points that you raise, but rather on how they relate with the topic.
1.1. "...you might even forget that you could actually add a patch version", really? I have hopes for the release manager to remember patches exist, but I'll be sure to remind him if he tries to bump the minor instead of the patch over a bug fix.
@tsheaff commented on GitHub (Apr 11, 2017):
@icorderi What about adding another method on the top-level API like
semver.pad('1.2', 3)which will return1.2.0(second arg defaults to 3)? This would be a nice helper, then the rest of the API requires that the semver have at least 3 parts.@jwdonahue commented on GitHub (Dec 8, 2017):
Implementation specific mappings between SemVer and any other string patterns is up to the implementer. There is nothing in SemVer that says you can't map onto other string formats. All it does define is what a SemVer string looks and behaves like. The SemVer triplet is a row of dot separated numbers, not a number in the mathematical sense. If it were, it would have to define fixed quantities of change for each of the dotted fields, and it certainly doesn't do that.
When you refer to version 3.1, you may very well be referencing a SemVer version, but which one? Is it 3.1.0, 3.1.4, 3.1.0-something? It's an obvious shorthand used to reference something in the class of version 3.1, but which object to instantiate is not always clear. It might refer to the range [3.1, 4), or maybe not. The SemVer spec has a clear context and fixed set of required and optional fields. Adding too many optional fields will increase the cognitive load on human users and complexity in tooling. If you want your tool to be more sophisticated than SemVer, that's great, nothing in the spec prevents you from doing so, but we should not require all tool developers to accept that additional complexity. In a sense, SemVer may be the lowest common denominator in the class of non-trivial version strings.
@zafarkhaja, you posed a great question, three years ago, and I think it has been answered. There have been many proposals to add/remove required fields from SemVer and all have crashed an burned. If you have no further questions and do not intend to submit a PR against this issue, please close it at your earliest possible convenience.
@bperrybap commented on GitHub (Dec 8, 2017):
@jwdonahue, the issue of version mapping is usually the other way around.
People are using version systems, methodologies (perhaps version control tools like git) and would like to be able to automatically map their version information to semver versions. The issues with semver is that it takes a hard handed approach and makes assumptions about how development is done and assumes the version number of the next release is known during the development cycle.
Those types of assumptions being made are often incorrect.
The entire argument for not allowing missing version information to be zero is very weak.
i.e. disallowing X.Y to mean X.Y.0 or X to be X.0.0
In my opinion, those suggesting that people would forget about patches or that having implied zeros is confusing should be embarrassed by those arguments.
The reason many of the semver suggestions have "crashed and burned" as you suggest, is that there is a very tight and heavy handed control over semver not because these suggested improvements to semver were not feasible, were confusing, or were not actually making semver better and more compatible with other development systems or processes.
I stick by my conclusions from back in July 2016.
The key to working with semver is to quit trying to get those that control it to update it and make it better and more compatible with real world development tools and development practices but rather to simply abuse it. In my case, this allows using information from git describe to generate semver compliant version numbers including post release versions that are of a lower priority than the actual "official" releases.
i.e. use whatever versioning system/methodology you want, and use automated scripts/rules/tools to convert that systems version information to semver version strings as needed/required.
Simply ignore the semver terminology of "pre-release" and abuse semver to to do what you what you want by playing with metadata and taking advantage of the way the rigid priority rules work.
@jwdonahue commented on GitHub (Dec 8, 2017):
@bperrybap
Not true. SemVer specifies the rules for what to do with the version number when you release certain classes of changes. However, most sprints will have a specified goal of adding feature X or fixing bug Z, but when multiple teams work in parallel, it's perfectly normal for them to wait until they are feature complete to decide what version number to release.
As for the rest of your rant... I agree the SemVer team has been a bit sluggish, but even if they were in a big hurry, I couldn't support the proposed changes. Some folks, including me, prefer our standards to be stable. Too much churn is no standard at all.
@bperrybap commented on GitHub (Dec 8, 2017):
In terms of proposing that omitted lower significant version numbers default to zero
i..e
x is treated the same as x.0.0
x.y is treated the same as x.y.0
as being "unstable" or creating "too much churn".
Really? no way. Being opposed to this makes little sense.
It is no change to semver or any of its meaning or any of its precedence rules.
It is a simple parsing requirement and in fact when I write a semver parser it assumes this.
It is trivial and should be part of the spec to ensure that all parsers support this.
I have never understood why is there is any opposition to this.
It doesn't change anything in semver. It merely allows a short hand for version numbers.
In terms of the brokeness of semver....
And therein lies the problem.
You just described the actual problem that many people run into when trying to use semver.
Yes, deciding on the final official release number can be differed until the actual release, but
in some cases a version number/string must still exist in the code during development.
And semver does not support development build version numbers/strings that are not a lead up to a known release number because semver currently absolutely assumes that the next release number is always known.
Look at the actual semver document. It is riddled with the term "pre-release version" all over the document and never bothers to even mention or consider post release or developmental, or experimental versions.
This takes a very narrow view of how versioning information is used
During development there are many cases where version numbers are needed but yet the actual version number of the next release is not yet known.
And THAT is what was discussed in several of these github issues.
In some cases version numbers are built into the s/w.
When semver version strings are used in code, a semver version string must exist and the developer must put in something during development even before the next version number is known.
That is where semver falls flat on its face as
semver only deals with the last part of the development cycle; the final runup to a release.
For example, a release may be done; say it was 1.2.3
And then development continues. But during the development it is not yet know how many of the desired bug fixes & features may be implemented. Depending on how many get implemented, it may create a different version number. i.e 1.2.4 vs 1.3.0
There are many reasons this can happen but the most obvious is that a particular release date was higher priority than the feature set. There may have been a full intent to move to 1.3.0 but due to time constraints and/or s/w issues, the new features either didn't make it in or were backed out and the next release is 1.2.4 instead of 1.3.0
In that case under semver you would have now created 1.3.0 pre-release releases but yet ended up shipping a 1.2.4 release.
And the priority rules might end up picking the wrong version.
Also, there can be situations where 1.2.4 was being worked on after 1.2.3 was released, and all of a sudden a critical bug fix is required but it also creates some backward compatibility issues.
Under semver that would bump the release to 2.0.0 which is ok, but that means that a 1.2.4 release never existed but yet there were perhaps several 1.2.4 "pre-release" versions.
The biggest issue with semver is that it has no way to support developmental releases that are "post" a given release that are not part of any formal future release.
This is because semver assumes that the next release number is always known and so it only accounts for "pre-release" versions.
My suggestion to get around this semver limitation is simply to abuse it.
semver has priority rules that allow abusing them to ensure that you can create development release that are after a given release and yet not know the actual release that this code will be in.
In my view semver should not be using the concept of "pre-release" at all.
In my view that is a narrow minded view of things and has warped the document.
I believe that semver should stick to using precedence as documented in section 11, and a pre-release version of a release is just one of several types of releases that are of a lower precedence than the final release.
In other words, semver should be clear on how precedence is determined (without mentioning "pre-release" versions), then show examples of how to use the precedence selection along with meta data for pre and post release versions.
There are many mentions of "pre-release versions" in sections 9, 10, and 11, that really should not be mentioning "pre-release" but rather simply meta data and precedence.
In my case, I abuse semver by essentially creating what semver will think are "pre-release" versions, even though there are being created after the release. This allows active development to continue on before the actual release number is known, and semver precedence will avoid using these development builds since it is tricked into thinking they are pre-release which have a lower precedence.
@jwdonahue commented on GitHub (Dec 8, 2017):
It does change semver or you wouldn't be here arguing for that change. It will add complexity to the parsers, both for the version string and any range selector schemes.
Easily handled. If you chose to embed version strings in the code in your developer branches, you should make it perfectly obvious that those versions are not sanctioned for release. There are plenty of options for anybody willing to put a little thought into the problem. Use prerelease and build meta tags to encode the branch names and version the branches independently, or simply use a non-SemVer style string that stands out as not for official release purposes. The spec doesn't say "all must use this scheme for all versioning purposes".
Personally, I would never embed version strings in the product, especially by hand. Your dev-ops system should automate what version strings are generated for which build products and produce a log/manifest of version strings and content hashes. That's a bit over-simplified, but you should get my point...
If we renamed prerelease to not-a-release tag, would that make you feel better? I honestly don't understand what is so special about post-release. If I have the 2.0.0 release, then the fact that 2.0.1 is a post release of 2.0.0 seems quite obvious to me. Most of us have moved on from this already and use identifiers like dev and experiment in our not-a-release tags.
Sounds like a prerelease to me.
Not true, semver has the prerelease tag for this and anything that is not published need not apply. You are free to use any versioning scheme that fits well into your dev-ops systems.
Exactly! Now you are getting it. You can literally have 1.3.0-pre, 2.0.0-pre and 3.9.9-pre in simultaneous development and still go back and release 1.1.1 to fix 1.1.0. You are like one of those people standing on the bank of a large river who wants to go to the other side. There's a bridge to the left and one to the right, but you are insistent that somebody build the bridge that you have in mind at the spot you are standing on.
Can you give us an example? I'd say that if your scheme produces SemVer strings that adhere to specified semantics, then you are not "abusing" it, you are using it correctly. You may think it an ugly little bridge, but I am sure it can hold your weight.
I am inclined to agree that the prerelease tag is a misnomer. What we have is an intent to publish something that by convention is not the promised release and that doesn't always make sense relative to the way the tag is actually used. But lets please not attach any special new connotations to post-release, we already have too many problems to solve. The reality is that anything that is released after any given release, is a post release, even if it is retroactive, but it is also pre-release to later releases, even if it doesn't have any tags on it.
Version numbers are not and should never be used to track temporal relationships, except in the build metadata, so the whole pre/post argument really comes down to provenance. If you have 1.0.0, 1.0.1, 2.0.0, you know that 1.0.0 begat 1.0.1 and may have slipped some genes into 2.0.0, but maybe not. So the SemVer triplet is all about the kinship of one version to another and in this particular domain, time travel is possible (back-porting).
The optional sortable tag (aka prerelease) is used to say something about the kind of publication that is being made. Marketing has been promising v3 for months now, but the dev's want to flight some A/B feature tests or maybe the first release candidate to the early adopters, so they put this tag on there that carries whatever semantics they choose to embedded in its identifiers, but its very presence indicates that it is a transitive, probably unstable (dependent to some degree on those identifiers), limited support, publication.
But I ask, what kind of work happens post release? Do we spend our time and money developing towards something that will never be released? Well, maybe sometimes, but it's usually all intended to lead to something that we can release, and that really is how our optional sortable tag got its name.
@bperrybap, does that more or less sum it up? Maybe we just need to rename the bridge?
@bperrybap commented on GitHub (Dec 9, 2017):
@jwdonahue
No. Supporting version X as X.0.0 and X.Y as X.0.0 does NOT change semver.
It only changes the initial parser. Once you parse it nothing else changes. i.e the initial parser pulls in the rev, massages the revision for the omitted digits and then does EXACTLY what it does not. There would be zero changes to anything else. You are trying to make it more complex than it really is.
In other words you can still say that versions are X.Y.Z but that X or X.Y can be used and omitted digits will be assumed to be zero.
That limits it to the parser as all it as to do is create the X.Y.Z version numbers and insert the zeros if the digit is omitted.
The reason I say creating post releases is abusing semver is that it appears you are still not understanding the reasoning and need for creating post releases with an unknown next release number. It appears that you are still not understanding the issue and I think this lack of understanding is the cause of all the arguments.
Once this is understood, I think all the comments and suggestions that people have been making about this over the years will make sense.
I make this assumption based these comments:
I sounds like you are still assuming that semver strings are ALWAYS either a release or a "pre-release".
I have given several examples of this. Here is another.
version 1.2.3 has been release
Active development is going on. The semver string IS embedded into the product.
It is generated automatically when the image is built. The next revision number is unknown at this point.
What semver version string do you use?
Well, the answer is to abuse semver.
Just create a string that is "1.2.3-blah-blah"....
This will look like a pre-release to semver and be lower precedence than 1.2.3 which is what you want.
This is an example of a post release versions. It is post 1.2.3 so developers have a clue what it is based on and can use their source control tools to find it but the semver system will skip over it so it doesn't get used by "real" people.
And if you create tags in git that are the semver version say "1.2.3" in this case, you can use 'git describe" to create your post release version numbers.
Now do you understand?
This is what people have been asking for for years now. A way to create developmental release that is post a known release but when the next release is unknown.
The semver spec is currently too rigid in its thinking that version strings are only every used by external people and as a result assumes that the next version number is always known.
So yes I think removing most of the "pre-release" type wording and assumptions would be a very good thing.
And then have examples of how to use the semver version strings for both pre and post release for both internal and external consumption.
@FichteFoll commented on GitHub (Dec 9, 2017):
This has turned into #200 now.
I'd like to go back on topic and focus on this:
There have been several arguments so far about why changing this isn't quite good, but what argument is there for allowing the omission of trailing zeroes other than laziness?
@jwdonahue commented on GitHub (Dec 12, 2017):
@bperrybap
Again, I must reiterate that the proposed changes would add complexity to parsers and more importantly, it will break existing parsers, many of which were implemented, precisely because SemVer is stable. As @FichteFoll points out, no evidence has been presented that omitting trailing zeros conveys any real advantage.
@zafarkhaja, if you have nothing further to add here, please close this issue at your earliest possible convenience.
@jwdonahue commented on GitHub (Jan 22, 2020):
@zafarkhaja, I would draw your attention to the two regex's in the FAQ. Are you prepared to spend the next year shepherding changes to those through a PR? Since I don't see any concrete language suggestions in the form an RFC (see CONTRIBUTING.ms), please close this issue at your earliest possible convenience.
@bperrybap commented on GitHub (Jan 22, 2020):
@jwdonahue
What I've seen over the several years that people have been asking for this and a few other capabilities related to developmental/internal releases, is that all the comments and responses from those who have the ability to accept any of these types of updates/changes have been absolute and resounding rejections.
They were simply never even open to considering any of these types of capability updates/changes.
IMO, the maintainers were focused on solving a particular set of issues, and were completely blind to addressing a few other issues that could also be resolved with a few tweaks to how the revision string is parsed/processed. The maintainers seemed to believe that the requests for these enhancements were unnecessary and that users should conform to semver as it was defined, which is very heavy handed and not always possible for certain development methodologies and practices.
semver currently falls flat on its face for certain types of developmental release or branch releases prior to a known final release because it has never addressed non stable releases other than by having early pre 1.0.0 releases with major version 0.
As I've mentioned a few times in this thread and a few others, there are ways to alter the parsing to accommodate many of the things that people are asking for and are needing and yet NOT change what the actual semver revision numbers and priority rules mean.
It would merely be slightly altering the way the string is parsed to be a little more forgiving (which is always a good thing), and not making any changes to what the parsed string version numbers mean.
If there is now the possibility of submitting a PR for these types of updates, it implies that there must now be a rethinking of things from those in charge to be less strict about the revision string format.
I would like to see something from the maintainers related to their openness to accepting these types of capability updates from a PR (beyond the "Participation commitment" statements on the "Contributing" page). before spending any time creating and submitting any sort of PR.
Otherwise we just enter a world of "bring me another rock" rejection which is a waste of time and nothing ever changes.
@jwdonahue commented on GitHub (Jan 22, 2020):
@bperrybap
Until recently, "they" were either @mojombo, or @haacked, and there wasn't a lot of overlap between them, and they've mostly moved on. Today, the maintainer's list is longer, and they are mostly the representatives of package tooling owners. I think they've had it for about a year now? Anyway, I can't really do justice to covering @mojombo's motivations for creating the standard initially, but I think it was under his watch that it evolved from v1 to v2 (oh! there's that short-hand notation again). Pretty sure that by the time v2 stabilized, there were at least a handful of SemVer supporting tools with major customer bases, and v2 probably represents a reasonable compromise between those tool owners and @mojombo. But then, it did take a very long time to get Nuget on-board for v2 support, so maybe that's not a very accurate intuition? Then @haacked seemed to have focused on getting this github site up and running and coordinating a lot of language translations.
Everyone involved in the care and maintenance of the SemVer spec and site, do so on a part-time basis. One of the first things that the current maintainers accomplished, was the development/release of the CONTRIBUTING.md, which is fairly explicit regarding their determination to keep SemVer stable.
Yup, that's why I suggested the regex modification exercise. It took the better part of year of group effort (part-time) for a handful of us to drive that change into the FAQ. I am pretty sure there's at least one packaging tool that uses one of them, and I am certain there are many that don't use any regex's, or they use several, sequentially. I suggested the exercise, because it represents the low-end of the range of complexity required to change SemVer parsing code. Multiply that effort by a dozen or so tools with large customer bases, then times it by about 20, for all the bureaucratic effort required by those organizations to get anything done (I'd say that's conservative). But lets not forget the tens of thousands of lesser tools/scripts, deployed in hand-built build systems and the great noise they will generate when the proposed change is actually adopted by a large fraction of packing tool providers!
Adoption of proposed changes into a large fraction of tool chains, is now a prerequisite for making changes to SemVer semantics.
The OP's proposed change is a breaking change. Getting from v2 to v3 requires solving the disambiguation problem (IMHO). There's probably millions of API's/packages out there that already have v2 strings on them and once we open the door for v2+n, there's going to be a flood of other things to squeeze in there. We need to ensure that the next iteration, makes it easier for future iterations to co-exist with there predecessors, and for legacy code to fail gracefully in the presence of unsupported strings.
I would also like to point out that when we discuss versions, we often use short-hand, like
v1for instance. To what do you think I am referring? Did I mean[1.0.0,2.0.0)or[1.0.0,1.0.0]? The OP's proposed changes would dictate the later, but then what short-hand would we use for the former? I would be willing to bet the price of a pitcher of beer, that there already are tools that have relaxed input string filtering that convertsv1to one or the other of those choices, and in some cases, use other notations as selectors, for which one to convert it to. Thevcertainly isn't SemVer 2 compliant, yet it's accepted by many tools.I believe the conventions around this sort of thing actually vary across system and programming language environments. Therefore, broad adoption of the "one true way", as specified by the OP is unlikely.
It is better to think of SemVer as a kind of design pattern to be considered/applied in the development of software development tool chains, rather than an inter-op standard of the types that buttress the internet. It's well suited for the former use, and totally inadequate for the later. We get a lot of change requests here that really should be taken up with the tool developers. There's just too much diversity among the tool chains to get most of those requests adopted.
Go and issue PR's in the package development repo's for your favorite changes. Get them adopted by as many packaging tools as you can, then maybe a semantics altering SemVer RFC has a chance of being accepted. Otherwise, this site is mostly about honing the meaning of the existing language, answering questions from tool developers, and providing more and better language translations.
@steveklabnik commented on GitHub (Jan 22, 2020):
It's been a while, it's true. I have not had as much time as I would like to really push things forward, so things are moving slowly, and I think that's okay for such a broad spec. I also completely understand the desire to talk about things before they're implemented, and I think that's totally fine. Just don't have the bandwidth for the discussion right this second.
@bperrybap commented on GitHub (Jan 22, 2020):
It depends on how "breaking change" is interpreted.
While it does break parsers, it does not break the actual semantics of the meaning of the version numbers and their priorities.
The missing sub values are just filled in with zeros. i.e. 1 or v1 would be 1.0.0 and 1.1 or v1.1. would be 1.1.0 etc...
What is frustrating and a bit infuriating, is that these types of things were proposed long before semver was widely adopted, and now it is a much more difficult task since there are so many different parsing implementations out there.
With respect to interoperability in communications systems, there is a saying:
"Be very liberal in what you accept and strict in what you send. This ensures maximum interoperability.
This is missing in semver.
IMO, semver has mandated unnecessary strictness on what it accepts for a string.
What the OP wanted could have done by specifying that an optional leading 'v' could be present and that missing sub versions numbers would be inserted as zero.
below here is out side of this issue but somewhat related in how I worked around semver limitations
semver has never addressed how to deal with unstable/temporary developmental releases, after an official release, when the actual next official release number is not yet known.
To me as well as many others, it is a big missing capability.
There were many semver github issues created about this missing capability.
I got there for both of these issues (short version numbers, and post release developmental versions) by giving up that semver tweaks for this stuff would ever happen and simply started abusing the documented way to use semver identifiers and metadata to handle this.
By doing this, it allows the ability to programmatically create semver "compliant" version strings for developmental release directly on the fly from git version and git tag information that are still interpreted with the appropriate/desired priority.
I created regex processing scripts that can process version strings and convert them to semver compliant version strings when needed. They are much less restrictive than what semver demands.
Things like leading 'v' or missing sub version numbers are supported.
It allows the possibility of using internal revision numbers/strings and can convert them when needed to semver compliant strings.
I've mentioned this before, but perhaps an answer for creating semver compliant developmental release version strings may be to simply tweak the semver documentation to show people how to use/abuse the semver strings to do some of the things they want while still creating semver compliant strings.
Even better would be to tweak the documentation to expand it to include additional use cases for these fields for things like post release developmental builds and to show people how to create those developmental release versions within the current semver string parsing requirements by showing how to use the identifier and metadata to create development builds that are post a known release but have a lower priority than the last official release even when the next release number is not yet known.
This is a big thing that is missing in semver (at least in its documentation) and is what created so many of these semver github issues.
semver historically has taken a very narrow view of development and assumes that releases are only being made leading up to an already known release version, and THAT is the problem since that is not always the case in the real world. i.e. semver should allow creating release versions that may never see the light of day outside of development and are done post release before the next release number is known.
So perhaps the post release version string when next version number is unknown can be solved through expanded documentation and expanding the use for the identifier and metadata fields.
@jwdonahue commented on GitHub (Jan 23, 2020):
You seem to think that the mapping from v1 => 1.0.0 is the only correct or best answer. I am saying that it is not. It might work for you, but it does not work for everybody, or even for most of us. If your work-around is good for you, that's great.
SemVer defines a specific syntax that is also used to describe its semantics. The syntax match is used in many tools to decide whether SemVer semantics apply to the string at all. Because
v1and1are not SemVer strings, you are free to do whatever you like with them, including any arbitrary mapping onto SemVer that you think is appropriate for your use cases. If you add the OP's proposed additional syntax, you are over-constraining what tool developers are allowed to do. Changing the SemVer syntax or its semantics are breaking changes. Even if it were true that there would be simple fixes available, it's still a breaking change that would force tool developers to comply or drop SemVer support.I do not see any good reason to add the extra syntactic sugar to the spec. Usually, these kinds of requests really boil down to the OP wanting their particular tool to behave a certain way and they think if they can just get the spec changed, then the tool owner would comply. In most cases, it would be easier to get the tool owner to add the optional feature, or tweak the tool yourself, than to change the SemVer spec. Many packaging tools already support a range of version syntax's and range specifications, some of which have different semantics than SemVer.
@bperrybap commented on GitHub (Jan 23, 2020):
It does work for all those that subscribe to a concept of a MAJOR.MINOR.PATCH revisioning system.
For those that don't subscribe to that, then semver is likely not for them at all and, IMO, they are SOL.
And for those that do, filling in the missing fields is the correct way to handle it as it allows for using shortened version numbers when possible if desired. (like when patch is zero)
In over 40 years of of s/w development I've seen many different ways of doing version numbers.
Most tended to use MAJOR.MINOR.PATCH the same way that semver has defined.
And some projects - even big ones - do things in totally retarded ways. (FireFox is a great example of one that started out with MAJOR.MINOR.PATCH, but then went bonkers for a while with just a single number - which is totally retarded, but now went back to the more sane MAJOR.MINOR.PATCH).
But I have seen many projects over the years that would eliminate the patch number when it was 0.
And this is where it would be useful to have a parsing rule that could allow this.
What I've been saying and several others agreed, is that semver string parsing could have supported shortened version numbers by filling in missing numbers with zeros. This would have provided a simple yet consistent way for how to get from shortened version numbers to the MAJOR.MINOR.PATCH number that semver needs for its rules.
It isn't about making semver support alternate versioning numbering systems but merely how to have a smarter less restrictive parser that can get to the version number information that semver wants/needs.
What semver really defines is the rules around a 3 point version system. MAJOR.MINOR.PATCH (and some rules for identifiers)
How to get from a string of characters to that information and to those numbers could be less strict than the way it was defined. i.e. the parsing of the string could be a little less strict and forgiving.
Some of the additional things that people wanted could be done slightly differently, and people might be willing to do them, if they understood how.
For example, for those that wanted to have a build number after MINOR, they could likely use an semver identifier instead without to much difficulty.
But the semver documentation doesn't talk about this, so some may not see how to get there from what they are used to.
Another big issues for many projects that has been brought over and over again is that semver has yet to officially deal with the issue of how to create a version string for post release developmental releases before the next release number is known. This is a serious issue that I believe was not ever taken seriously by the semver development team.
IMO, how to create a version string for developmental/internal releases when the next release number is not yet known yet is a big enough issue that it should have its very own entry in the FAQ.
This issue came up over and over again in the semver github issues so I would say it was definitely a frequently asked question.
The only response from semver maintainers I saw in the github issues was basically "you shouldn't be doing that.
The current work around I use for this is to abuse the identifier fields to trick the semver priority rules.
Based on existing rules this will make post release internal development releases a lower priority than the release that they are based off of even though they occur after that release, since semver will assume that the developmental release done prior to the release it was based on given rules no. 9 and no. 11. Which is very useful for many internal development and testing purposes.
i.e. this tricks semver into thinking they are pre-releases even though they are post releases.
IMO, semver needs a few new entries in the FAQ about how to create semver version strings for some common non semver ways of doing things.
I think this could a long way for many people trying to figure out how to put their existing information into semver compliant release strings.
For example,
My scripts currently use regular expressions do this:
@ljharb commented on GitHub (Jan 23, 2020):
v1in npm's ecosystem maps to1.x, which is the latest published version with a major of "1" - this is decidedly not the same asv1.0.0which would disallowv1.0.1. They carry different semantics; convey different intentions.@bperrybap commented on GitHub (Jan 23, 2020):
Ah, so npm allows wild carding? yep very different.
@ljharb commented on GitHub (Jan 23, 2020):
I'd say human intuition allows wildcarding; it's very unclear to me (absent npm context) whether
v1means "the first v1", "the last v1", "all v1s together as a group", "a particular v1", etc.@jwdonahue commented on GitHub (Jan 23, 2020):
Like I said,
v1 != v1.0in many many cases. I think of all the nonconforming strings likev1as potentially simple native language references to a class of versions. If the context happens to be SemVer, I usually do the mapping to1.z.y, which is very common.@jwdonahue commented on GitHub (Jan 23, 2020):
@bperrybap
As for all the other things you like that haven't gained traction here, they just aren't on topic for this thread.
@bperrybap commented on GitHub (Jan 23, 2020):
Totally agree. I'll start a new issue for them even though there are several existing issues about them.
I'd like to start a clean/fresh issue for discussion since think many of those other issues requesting additional semver capabilities could be cleared up and even resolved for quite a few people with just documentation and FAQ updates to show people how to use the existing semver version string capabilities for their additional favorite bits of information.
@jwdonahue commented on GitHub (Jan 23, 2020):
See also:
#168 How to behave if a project uses SemVer, but its maintainer is made to show the version of that project in SemVer incompatible format?
#344 Specification of normalizing non-semver to semver.
@jwdonahue commented on GitHub (Jan 23, 2020):
@zafarkhaja
Can we please close this thread now? It has near zero probability of gaining any traction towards modifying the spec or the FAQ. Unless you intend to begin the process of issuing an RFC, this thread doesn't need to be left open.
@bperrybap commented on GitHub (Jan 23, 2020):
I do think that this issue is worthy of a FAQ entry.
I think it would be useful to have an FAQ entry that mentions that version strings such as MAJOR or MAJOR.MINOR or MAJOR.x or npm vMAJOR or vMAJOR.MINOR are semantically incompatible with semver.
i.e. 1 or 2.1 or 1.x or npm style vMAJOR style numbers
That way if this issue every comes up again, it can be pointed to the FAQ and closed.
@jwdonahue commented on GitHub (Jan 24, 2020):
The FAQ is not the spec. I would point you to semver.org for a description of conforming syntax. There's really no reason to attempt to list even a small fraction of all the non-conforming forms of version strings out there.
But you are always welcome to issue a PR.
@zafarkhaja commented on GitHub (Jan 25, 2020):
@jwdonahue sorry, I was away for quite a while but I'm closing the issue now.
P.S. I still think it's only practical to be less strict about the (string) representation because SemVer is more about the concept, so I might follow up with an RFC later... Thanks everyone.
@sjmiller609 commented on GitHub (Jul 11, 2023):
For anyone ending up here looking for a way to parse a string that might not include minor or patch, you can parse with the Comparator struct https://docs.rs/semver/latest/semver/struct.Comparator.html