mirror of
https://github.com/semver/semver.git
synced 2026-03-22 14:10:15 -05:00
Make patch number optional #280
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: github-starred/semver#280
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 @hofmand on GitHub (May 17, 2017).
I write Windows software to communicate with an embedded controller that uses only 16-bit integers. The person who programmed the DSP decided to use the upper 8 bits of one memory location as the major version number and the lower 8 bits as the minor version number. To make it easier for the Windows side to work with multiple DSP versions, I asked the programmer to increment the major version for every release that had breaking (incompatible) changes, so in that way this scheme is similar to SemVer. What's different is that we don't use a patch number. Instead we treat the minor version as the patch version.
So I think it would be good if SemVer made the patch number optional.
Also, with only 8 bits to work with, it's conceivable that the minor version number may overflow. It might be good for the SemVer spec to explain what to do in that case.
@silkentrance commented on GitHub (Nov 22, 2017):
Please close and have a good laugh.
@jwdonahue commented on GitHub (Nov 28, 2017):
@derekhofmann, SemVer defines a string format for encoding version information. Your particular binary format requirements are outside the scope of the SemVer spec.
@silkentrance commented on GitHub (Nov 28, 2017):
@derekhofmann since there are only two fields in the version number. Perhaps you can translate that into just MAJOR.0.PATCH. That way, the MINOR always defaults to 0.
Alternatively you could ask the DSP programmer to reassign the bits of the version id, say 5 bits for MAJOR, allowing you to have 31 different major releases excl. 0. And 5 for PATCH, allowing you to have 31 different patch releases excl. 0. And this leaves you with 6 bits for MINOR, again allowing you to have 63 different minor releases per major release excl. 0.
So, given that most of the breaking changes might have happened during inception of the DSP software, and we consider the major to be 0, e.g. 0.9.0
Of course you have to readjust the number of bits assigned to each component of SEMVER, depending on your exact requirements. Or simply stick to the MAJOR.0.PATCH pattern.
@hofmand commented on GitHub (Nov 28, 2017):
I see, two- or three-number versioning cannot or should not be a subset of
SemVer's four-number versioning.
On Tue, Nov 28, 2017 at 2:41 AM, Joseph Donahue notifications@github.com
wrote:
@silkentrance commented on GitHub (Nov 28, 2017):
@derekhofmann of course it can, but you need to fill in the blanks
@silkentrance commented on GitHub (Nov 28, 2017):
@derekhofmann and why would semver have a four number versioning scheme? do you mean the optional prerelease tag?
@hofmand commented on GitHub (Nov 28, 2017):
Yes, allow me to restate: two-number versioning cannot or should not be a
subset of SemVer's three-number versioning, correct?
On Tue, Nov 28, 2017 at 1:38 PM, Carsten Klein notifications@github.com
wrote:
@jwdonahue commented on GitHub (Nov 28, 2017):
@derekhofmann, technically, the version numbers defined by SemVer can't ever overflow, though they might become way to long for even a C string to hold on some architectures, it is unlikely to be a major problem on modern systems. Does the DSP board really lack the space to store 60 bytes of version string?
You could probably assume that the DSP architecture used, will be obsolete before the software ever reaches a two or three digit major number. It's probably also safe to assume that the minor number will never exceed four or five digits, so that's [3].[5] for major and minor, leaving room for a few hundred patches per day (unlikely) and a DSP lifespan of at most twenty five years, you should only need seven digits for that. A hundred bytes or less should be enough to hold that products version string for the conceivable lifespan of the product.
But why go there? The SemVer need not be embedded in the DSP. All you really need to do is store a sufficiently long key value enabling you to lookup the SemVer and any other data regarding that product version. I like using the full commit hash (the first six or eight digits also works) from the code that is pulled from the repo, to build the product. When the build/test cycles succeed, tag that commit hash with an appropriate SemVer string. For that matter, a sequential build number is probably adequate.
When you decide to pull new bits for the DSP, you are likely referencing a file store somewhere and downloading a directory or package of some type. All that is really needed is for those to be properly labelled, such that you can decide which one to download. There should be some sort of readme/version/manifest file that contains hash values for the tracked artifacts along with the SemVer string for that set.
@silkentrance commented on GitHub (Nov 28, 2017):
@derekhofmann The mapping scheme proposed by @jwdonahue is actually a good one.
And, given the fact that older releases of the DSP might be still out in the field and must still be recognised by your software, I would propose to start from scratch and just set the MSB to 1, indicating that this is a mapping instead of a version number, now utilising both bytes.
From then on, the DSP programmer will only increase the bits 0..14 and leave the MSB at 1.
Older versions of the software can still be recognised, as they do not have the MSB set to 1.
Unless, of course, your current versioning scheme already sets the MSB to 1.
But you get the drift. Sort out the process and you are good to go, especially with the information provided in https://github.com/semver/semver/issues/375#issuecomment-347680200
@hofmand commented on GitHub (Nov 28, 2017):
The DSP and the software that talks to it have independent development
lifecycles and so a lookup table won't work for us.
On Nov 28, 2017 14:40, "Carsten Klein" notifications@github.com wrote:
@jwdonahue commented on GitHub (Nov 28, 2017):
Actually, in the absence of a built-in SemVer string, a lookup is exactly what you need for independent development cycles. All your code needs to know is which version of the DSP code it's talking to, yes? But you would need the cooperation of the DSP developer to maintain the mapping. Either you find a workaround that is or maps to SemVer, or you simply have to give up on SemVer. It's not designed for fixed field binary representations and I for one would be adamantly opposed to relaxing the standard for corner cases that don't have a few dozen bytes of storage available.
@hofmand commented on GitHub (Nov 28, 2017):
A mapping would require a new version of software whenever the DSP changes,
and we don't want that. The software needs to know whether the DSP has made
any breaking changes to the communication protocol, which is what SemVer is
good at. The only issue is SemVer's 3-number requirement and its silence on
what to do when a number overflows its underlying data type.
On Tue, Nov 28, 2017 at 3:38 PM, Joseph Donahue notifications@github.com
wrote:
@jwdonahue commented on GitHub (Nov 29, 2017):
@derekhofmann
It is not possible for a SemVer version number to overflow, you just keep adding digits to the string and it just doesn't make any sense to weaken the standard for this corner case. There just aren't many devices that lack the resources to hold a SemVer string. We've tried to give you alternative workarounds for the limitations that you are facing, it's up to you to adapt to your reality.
I vote that you should close this issue at your earliest possible convenience.
@hofmand commented on GitHub (Nov 29, 2017):
The standard says, "A 255 character version string is probably overkill,
for example. Also, specific systems may impose their own limits on the size
of the string." So it logically follows that version numbers can overflow.
On Nov 28, 2017 16:58, "Joseph Donahue" notifications@github.com wrote:
@derekhofmann https://github.com/derekhofmann
The only issue is SemVer's 3-number requirement and its silence on
what to do when a number overflows its underlying data type
It is not possible for a SemVer version number to overflow, you just keep
adding digits to the string and it just doesn't make any sense to weaken
the standard for this corner case. There just aren't many devices that lack
the resources to hold a SemVer string. We've tried to give you alternative
workarounds for the limitations that you are facing, it's up to you to
adapt to your reality.
I vote that you should close this issue at your earliest possible
convenience.
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/semver/semver/issues/375#issuecomment-347716477, or mute
the thread
https://github.com/notifications/unsubscribe-auth/AFtQ8T94w5tq-E4xmC0LlaUjRjV6rFm9ks5s7KwigaJpZM4Neahx
.
@jwdonahue commented on GitHub (Nov 29, 2017):
@derekhofmann
What do you think the spec should say about it?
@silkentrance commented on GitHub (Nov 29, 2017):
@derekhofmann Normally, a software undergoes a certain lifecycle. And when that lifecycle is over, one either starts from scratch with an altogether new version, starting from scratch at 0.0.1. E.g. suppr and suppr2.
In addition, the individual fields in the version string will find their natural limits not defined by string length but by reason. While it can make sense to have 300 patches per minor version, one should overthink their development process and their testing strategies.
And while 300+ minor versions per major can make sense, it is also not feasible to have that many minor releases but instead just increase the major once in a while.
Again for the major. While a major 20+ may make sense, one should think about ending the lifecycle of the product there and restart from scratch with a next generation product.
As such, there is no overflow and no artificial length limit set on the version string and its individual components. It is just an application of common best practices that will limit the individual components in a version string.
@hofmand commented on GitHub (Nov 29, 2017):
@jwdonahue, here's what I would change:
Make PATCH optional (this touches much of the spec).
In S.7 (spec item #7), add that the MINOR version may change in lieu of
PATCH if backwards compatible bug fixes are introduced but PATCH cannot be
incremented, for example if incrementing it would exceed the maximum value
of an underlying binary data type. ("It MAY include patch level changes"
does not unambiguously cover this use case.)
Add similar language to S.8 saying that the MAJOR version may change in
lieu of MINOR if MINOR cannot be incremented.
On Tue, Nov 28, 2017 at 6:10 PM, Joseph Donahue notifications@github.com
wrote:
@jwdonahue commented on GitHub (Nov 29, 2017):
@derekhofmann
Making patch optional just adds a little complication to parsing the string. I think it's been suggested before, but I don't recall if it's still an open issue or has been rejected.
I think the spec deliberately and rightly describes semantic versions as strings. There simply is no limit to how large any of the numeric fields can get. The FAQ's suggestion that 255 characters is probably pushing it, is subjective and I don't think @mojombo had the numeric fields in mind so much as the prerelease and meta tags.
I do not believe your resource restrictions warrant all the changes you're asking for.
@hofmand commented on GitHub (Nov 29, 2017):
@jwdonahue, do you stand by your earlier statement that handling edge cases
weakens the standard? If so, then I guess we will have to agree to disagree
on that point.
On Wed, Nov 29, 2017 at 1:30 PM, Joseph Donahue notifications@github.com
wrote:
@jwdonahue commented on GitHub (Nov 29, 2017):
@derekhofmann, you could always write up a 'Scalar Versioning Based On Semantic Versioning' specification. If you were really motivated, you might even provide guidance on how scalar bit fields map onto semver strings.
I vote for this issue to be closed.
@hofmand commented on GitHub (Nov 29, 2017):
@jwdonahue https://github.com/jwdonahue, please answer the question.
On Wed, Nov 29, 2017 at 1:49 PM, Joseph Donahue notifications@github.com
wrote:
@jwdonahue commented on GitHub (Nov 29, 2017):
@derekhofmann, It is my opinion that the proposed solution to this particular edge case would weaken the standard, yes. This is why I recommend that you write up your process as a proposed standard and then think through how you would translate from the scalar form to the SemVer form while insuring SemVer's semantics still hold. It is perfectly obvious to me that SemVer could be changed to match up with any of hundreds of known schemes in use over the decades, the real question is, should it match yours?
My answer to that last question is, no.
@jwdonahue commented on GitHub (Jul 14, 2018):
@hofmand
The version triple is central to the SemVer spec and is unlikely to be changed. Unless you intend to issue a PR with new proposed language for the spec, or you have additional questions, please close this issue at your earliest possible convenience.