mirror of
https://github.com/semver/semver.git
synced 2026-07-11 04:52:47 -05:00
[Question] How to increment semantic version to indicate change of supported developer board(s) #481
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: github-starred/semver#481
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 @sk-banerjee on GitHub (May 31, 2021).
Let's say a software project started off with support for 5 developer boards, and a version 1.0.0 (e.g., boards like raspberry Pi). Overtime compatible changes are made and version increments to 1.5.0.
After 1.5.0 release support for 2 more developer boards is added, but no changes in public API. To indicate addition of supported hardware which version number is recommended to be used? I think it cannot stay at 1.5.0 as there has been a tangible change?
Let's say after some more time, one of the boards goes out of production, again no change in public API. At this point how to change the version to indicate that a board is not more supported.
@ljharb commented on GitHub (May 31, 2021):
You added something - so, minor.
When something becomes no longer supported, it’s a breaking change - so, major.
in other words, the platforms you support is a part of your public API, so it is in fact changing in all these scenarios.
@alexandrtovmach commented on GitHub (Jun 14, 2021):
@sk-banerjee is it helpful?
@StingyJack commented on GitHub (Jun 25, 2021):
@sk-banerjee - none. unless you changed your software.
Versions of software apply to the software, not to the hardware that is supported by that software.
Consider Android OS - device manufacturers make hundreds of new devices each year. The version of android is not affected by what devices it is installed on or works with. The version is representative of the software and its capabilities.
@jwdonahue commented on GitHub (Sep 5, 2021):
@sk-banerjee
Assuming you are versioning a collection of content or package, adding non-breaking/backward-compatible changes requires a Minor bump. You cannot release two different sets of content that have the same version number on them, your change is not a bug fix and you've added new features (board support).
If you really were just versioning an API, there would not be any such thing as "supported hardware". Supporting hardware implies implementation, therefore you are likely versioning a package/collection of interfaces and implementations.
Depends on whether you are removing support for that board or not. The board going out of production, doesn't remove it from the environment or mean you have to remove support for it. It's often the case that software publishers continue to release new features and bug fixes for older hardware that's gone out of production. If you intend to remove support for the board from your software, you SHOULD first issue a minor update that includes a deprecation notice, then you MUST eventually issue a major (breaking) update that removes the relevant components.
@StingyJack
Like many other OS's, I think you'll find that the Android OS version number is a marketing number, not a SemVer string. Your analogy doesn't quite fit the problem here. Most modern OS kernels sit on top of a hardware adaption layer (HAL) that is often comprised of bits supplied by the hardware makers, so the kernel version wouldn't have to change. Ignoring apps, OEM's often customize Android configuration and code in order to differentiate their products, so my Pixel phone's droid OS is not the same thing as what's on a Samsung, even if both have Android 11, they do have different versions of OS kernel and HAL components in them.
Even if they contained identical kernel and app versions, the new hardware has it's own HAL installed and is a different collection of files. In fact, they have different package names and version numbers/histories, Pixel-xxx/Sumsung-yyy.
@StingyJack commented on GitHub (Sep 6, 2021):
@jwdonahue - he is asking about how to use semantic versioning to represent supported configurations. A program version and the list of configurations it supports are two different things that dont make sense to mix, which was the point I was trying to get across with the example. Software can exist that will work on a hardware platform created later. If the later hardware is tested and deemed supported, then add it to a supported list for that program version. It doesnt make sense to change the software version and the ceremony of a release when adding supported hardware configurations for a version of software.
Also a HAL as a contract and subsystem that would be defined by the OS not the device manufacturers. The HAL simplifies the OS need to control for example a PS/2 mouse vs a USB mouse and treats it just as a "Mouse" but uses the correct driver and function for the device action.
I had a Nexus 5, had to replace it and picked a Samsung A50 not realizing the depths of bloat and nonsense Samsung has come up with recently. Well played with the pixel choice.
@ljharb commented on GitHub (Sep 6, 2021):
@StingyJack they are not different things, and the thing that doesn’t make sense is attempting to separate them. Since a version is a snapshot, the hardware it supports is either what it declares regardless of future new hardware, or, it’s “whatever it works on, even if that hardware is invented a hundred years from now”. The latter isn’t always sustainable but is a helpful way to guide flexibility on the former.
@ljharb commented on GitHub (Sep 6, 2021):
Put another way, the relevant question is: “does vX.0.0 work, on this hardware, in this environment? if so, then semver dictates that v.X.Y.Z must work too, and if the next version won’t, then X must be incremented”
@jwdonahue commented on GitHub (Sep 6, 2021):
The OP wasn't specific in this regard, but the phrasing of the question indicates that "support for 2 more developer boards is added" to something and appears to be phrased as if that something is what they are applying the version number to. Probably a package or collection of interfaces and implementations.
A purest would version the Interface and the implementations separately. There are cases where this makes economic sense as well. In practice however, what is usually being versioned is not just the interface or API, it includes all sorts of implementation details. Separately versioned implementations/configurations add complexity to the build, test and publication systems that may not be warranted until you get above a certain Target-versions per API-versions level. It's not a topic that can be covered well in this particular forum.
There can be important advantages to consumers of your API's and implementations, if you do package and version them separately. Fixing a bug in an implementation for environment B1 requires a minor version bump of something. If I use your product on B2, my automation doesn't have to download, test and deploy a new package. Removing support for B1 doesn't imply a breaking-change barrier in the version history of B2 as well, so when you release a bug fix for B2 after the B1 removal, I don't have to commit human resources to evaluate what was broken, or whether the risk of taking a breaking change is worth the benefit of taking the fix.
Consider this hypothetical history for P:
1.0.0 // API and B1 implementation.
1.1.0 // Add support for B2.
1.1.1 // Bug fix for B2.
1.1.2 // Bug fix for B1.
1.2.0 // B1 is deprecated.
2.0.0 // B1 removed.
2.0.1 // Security fix for B2.
If I trust the publisher and my product is for B2, my automation might download, test and deploy 1.1.1 and 1.1.2 because they are both bug fixes, but the publisher has no way to signal to my automation whether either of the fixes applies to B2, I would wind up churning my own product for no good reason, so I might not allow fully automated bug fix releases, but that has important security implications for me and my customers.
Let's say that most bug fixes, actually target multiple boards because they share common code. Maybe the publisher's churn rate isn't too high for me to propagate automatically because I benefit from nine tenths of the changes, and it's just simpler to take all the bug fixes. But I can't propagate breaking changes, either automatically, or possibly even manually. So I can't take the critical security fix for B2 in 2.0.1 without executive approvals and all the days of meetings and dozens of emails that entails. Meanwhile, me and my customers are exposed to an avoidable liability. Any delay in releasing a critical security fix will impact our reputations and may lead to monetary damages.
If you're thinking I can just read the change history and decide to take P-2.0.1 into my product without propagating the breaking change through to my products version number, you are sadly mistaken. The fact that I am a purveyor of bits for B2, does not in any way constrain my customers from also supporting B1 AND taking a dependency on P. This is the classic diamond dependency problem (see Dependency Hell).