I am seeking guidance for the following scenario -
Assume that we have the following multiple production versions of a public API -
1.1.0
2.1.2
If a bug/defect was identified in the "1.1.0" version fixing which would introduce a breaking non-backward compatible change, how would the versioning need to be handled? Following semver, a breaking change would necessitate incrementing the major version - so "1.1.0" should become "2.0.0". However, we already have the next major version "2.1.2" live with its own changes.
Is it advisable to skip numbers between major version upgrades to accomodate for such scenarios? i.e. the next planned major version after "1.0.0" should have been "3.0.0"?
Any other suggestions?
so "1.1.0" should become "2.0.0"
Not true. Not only do you already have a 2.0.0, the semver spec doesn't require monotonicity. You can release it as 3.0.0 or 100.0.0. Normally however, this is where you would discontinue support for the 1.y.z series and encourage folks to upgrade to your existing 2.y.z.
Another option would be to merge the feature sets of 1.0.0 and 2.0.0 into 3.0.0.
ADDENDUM:
You made certain choices in the past, that affect the future evolution of your branded product, and your reputation as an organization. When you claim to be applying semantic versioning, you MUST not release a breaking change without bumping the major version number. The longer you adhere to the specified semantics, the more your customers will trust your claim.
You did not sign any contracts with a standards body in this case, but beyond that, none of us here at SO can advice you on your current legal obligations to your customers. It's up to you to decide at this point whether a strict adherence to semver is in the best interests of your customers or your organization.
Barring any contractual obligations between you and your customers, I would advice being as transparent with them as you possibly can. Explain your branding and versioning conundrum and rebrand your 1.y.z product, such that it can adhere to using semantic versioning. If you had product X, rename it X.Classic or some such.
Related
The semantic versioning system states that a backwards compatible bugfix means that you increment the patch version number (z in x.y.z). It also states that a backwards compatible feature addition should be introduced by incrementing the minor version number (y in x.y.z).
What if both of these things have been added a new release is due? Does one only increment the minor version number?
Semver is a great framework when each addition gets its own release. In this case, you would have ideally released the patch version updates for each bug fix, and then the minor version. However, having collated all those things together, your intuition is right. You can simply bypass the patch versions and bump the minor version. Just make sure to mention the bug fixes in the changelog to help your users know what has happened.
And remember, frameworks are meant to enable you to do things quickly, rather than be strict guidelines. So, nothing out there says that what you're doing goes against semver, it's just adapted to your way of working.
I've been using terraform for some time now and a doubt always come to my mind is, which versioning scheme is terraform-core using?
Is it semantic versioning AKA semver? Because if it is, why an upgrade in the minor version, as when upgrading a project from 0.11.X to 0.12.Y writes the state of terraform with that 0.12.x and it is not allowed to downgrade it back to 0.11.x?
Another thing related : why they opt for starting their version numbers in 0.X.X rather that 1.X.X? Does it mean anything?
They do use semantic versioning, but their interpretation is a little different than most.
Here's an answer on a GitHub issue from a Hashicorp employee regarding their versioning methodology:
At HashiCorp we take the idea of a v1.0 very seriously, and once Terraform gets there it will represent a strong promise of compatibility because we believe that the configuration language, internal architecture, CLI, and other product features are right for the long haul.
The current state of Terraform is a little more subtle. We do still consider backward-compatibility very important since we know there is a lot of production infrastructure depending on Terraform today. We must therefore make compromises so we can keep making progress towards something we could make v1.0 promises about. While we keep these disruptions to a minimum, they cannot always be avoided, and so we try to be very explicit about them in the changelog and, where applicable, in upgrade guides.
With this in mind, at this time we suggest always referring to the changelog before upgrading since this is our primary means to note any special considerations that apply during an upgrade. We try to reserve significant breaking changes for increases to the second (traditionally "minor") position in the version number, which at this time represent our "major" development milestones as we work towards an eventual v1.0.
Since Terraform is an application rather than a library we do not intend to follow the Semantic Versioning conventions to the letter, but since they do indeed represent common versioning idiom we are likely to follow them in spirit, since of course we wish to be as clear as possible. As #kshep noted, v0 releases are special in the semver conventions, but the meaning of v1.0 in semver is broadly consistent with how we intend to interpret it.
I'm sorry that our version numbering practices caused confusion here; based on this feedback, we will attempt to be clearer about the significance and risk of each release when we announce it and will work on writing some more explicit documentation on what I wrote above.
Ref: https://github.com/hashicorp/terraform/issues/15839#issuecomment-323106524
Better late than never: https://www.hashicorp.com/blog/announcing-hashicorp-terraform-1-0-general-availability
From here on you can expect regular semantic versioning support.
I have a large personal software library that I have been working on and is currently working on. Currently, its version is 0.1.0.
It is not mature enough to have a major version of 1. I keep modifying the code and introducing incompatible changes that would merit an increase of the major version number. At the same time, some of my other libraries depend on this library and refer to it by the version number.
If I introduce incompatible changes and don't want to increase the major version from 0 to 1, how should I increment my version number?
The SemVer website is not very clear on that, it just says:
Major version zero (0.y.z) is for initial development. Anything may
change at any time. The public API should not be considered stable.
Does "anything may change at any time mean" that an exception is made for a major version of 0 and that I can change the y and z numbers however I like?
For instance, if my version is 0.1.0 and I introduce an incompatible change, could the new version with that change be 0.2.0?
What others say
On this site it says:
In fact, the SemVer spec defines that anything starting with “0.”
doesn’t have to apply any of the SemVer rules.
Another site also seems to suggest that it is OK to increase the minor version when the major version is 0 and incompatible changes are added:
So you just continue through the 0.x.y range, incrementing y for every
backwards-compatible change, and x for every incompatible change.
It's up to you because
If other libraries depend on your software it means that your software has some consumed public APIs and if it has them... Why isn't already at 1.x.x version?
After all... why is so important that your software reaches the 1.0.0 version only once it's stable? It could start with 3.0.0 or 4.0.0 once it reaches a stable version...
Your software isn't mentally decoupled from your bigger project because, in fact, you'll consider it "mature" only when the whole software (made of a lot of smaller libraries) reaches a "mature" version. But from a technical perspective it's already decoupled 😉
It's right that starting from 0 you don't have to strictly adhere with the semver rules
Everything revolves around what is considered "mature". You told that your software isn't mature but what does it mean? That could be improved? That it doesn't cover all the corner cases? That it's not 100% tested?
In the end: if you don't consider it mature continue with the 0.x.y versioning and increase the minor version but your immature software is already consumed by other libraries so it should now reach the 2.0.0 version 😉
The rules for when to increase the MAJOR vs the MINOR version number with SemVer 2.0 are very compelling. They clearly give a lot of advantages to knowing if the app/service is backwards compatible.
But the site does not really give an reason for the differences between a MINOR and what it calls a PATCH. I don't see it giving the same benefits of MAJOR vs MINOR.
For reference here are the SemVer rules:
MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards-compatible manner, and
PATCH version when you make backwards-compatible bug fixes.
So the only difference between MINOR and PATCH is features vs bug fixes. My company wants to do that differently.
They want to have MINOR be a collection of [backwards compatible] features. "PATCH" (which we call Incremental) be the releases needed to get those features out. (We release bug fixes as we release features.)
For example, if we plan for 7 [backwards compatible] features in our 2.4 release then 2.4.0 may have 2 of the features, 2.4.1 would have 3 more features and 2.4.2 would have the last 2 (perhaps with a bug fix or two in each release).
I can see that this violates SemVer, but I need to know why SemVer has decided to be prescriptive on the differences between the MINOR and PATCH versions so I can know which way to push my company.
NOTE: I hope that this is not too subjective for Stack Overflow. I don't usually ask questions like this, so it is possible that this question will need to be closed...
The standard is deliberately terse. There's nothing in it that prevents you from releasing a bunch of bug fixes along with your new features and you only have to bump the minor field when you do this. If the changes only involve bug fixes, refactoring or documentation that does not add, remove or modify any interface, then you only bump the patch. The whole point is to communicate to your consumers, their level of risk when taking an update from you.
EDIT:
It is a best practice to separate bug fixes (patches) from feature work (minor) and breaking changes (major), into separate releases. This allows your consumers to automatically pick up the latest fixes, without having to deal with feature bloat or breaking changes.
For example, if we plan for 7 [backwards compatible] features in our 2.4 release then 2.4.0 may have 2 of the features, 2.4.1 would have 3 more features and 2.4.2 would have the last 2 (perhaps with a bug fix or two in each release).
Nothing stops you following SemVer convention and release 2.4.0 with 2 features, 2.5.0 with 3 more features and 2.6.0 with last 2 features and a few bug fixes for previously released features.
It is better to follow some common convention instead of reinventing the wheel. You save time thinking, discussing and documenting a custom solution as well as avoid confusion within the team and newcomers.
https://semver.org/
The Semantic Versioning Specification (SemVer) defines:
Major version zero (0.y.z) is for initial development. Anything may change at any time. The public API should not be considered stable.
So starting with 1.0.0 is considered stable.
When starting a project normally version 0.1.0 is used and gradually increased, there is a point where the project can have something like 0.20.3 for months/years and it is "stable".
Therefore would like to know what could be considered good practices to follow besides the criteria, arguments before bumping a project to server 1.0.0.
How you are dealing with this?
If there are not issues/code activity in 3 months the version is dumped?
The development team decides when they have version 1.0.0. It is possible for a project to remain in experimental/prototype mode for very long periods of time. The only thing that matters here is whether the interface and implementation can be considered complete or not. What are your goals? Do you have all the planned v1 features in place? Do you have doubts w.r.t. implementation conformance to the documented interface?
Some teams don't have workflows that map onto the full semver spec, but they use packaging/release tooling that requires a semver version string. In order to be legal, they never release version 1.0.0, so any version bumps literally don't have full SemVer semantics. See #4 in the spec.
When I see SomeLib.0.20.3.pkg I assume it is not stable. A breaking change can occur on the very next minor field bump, whether or not there have ever been any such changes in the past. SemVer is a contract that allows the SomeLib developers to break things without notice in this particular case.
There is nothing in the spec that precludes a team from issuing a 1.0.0 and then returning to a long sequence of 0.x.x releases if they so desire to operate that way. This is similar to, but not exactly the same as using prerelease tags. When you issue 1.0.1-prerelease you are at least implying intent to release a work derived from 1.0.0 that is a bug-fix, but the prerelease tag is warning label that you are not yet certain of the safety of the changes you made. Following on from 1.0.0 to a sequence of 0.x.x releases says you might not even be deriving from 1.0.0 anymore. Basically, all bets are off again.
If you require any further elucidation on this matter, please ask, I am happy to try to answer any questions regarding SemVer.