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.
Related
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 😉
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.
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/
I used node.js for a development project a few years ago, and this app is somewhat "mothballed" for the time being — it needs to stay online, it needs to stay secure, but it shouldn't need much attention. It is currently running on node.js v0.10.32, but I would now like invest in a "final" migration to a Long Term Support (LTS) release so it will be easier to maintain for the foreseeable future.
At first glance, the node.js homepage makes it look like v4.4.5 is obviously the only available LTS release:
However if I click that LTS schedule link, it tells a different story. As far as I can tell, version 6 of node.js is also slated to be an LTS release, with that support ending a full year later than version 4 will be.
Given that:
v6.2.0 is a versioned release
v6 is purported to receive LTS maintenance until 2019-04-01
theoretically no changes in v6.x should break backwards compatibility
Why would I bother upgrading to v4 instead of v6? Seems like v4 buys me one less year of security patches, but no additional compatibility guarantees?
With gratitude to jasnell and TheAlphaNerd who patiently answered my acerbic questions over on GitHub, here's my understanding of how node.js "long term support" releases are handled:
All releases based on an even-numbered major branch are what other projects might call a "long term support" version. They are promised at least 30 months of support from the first "cut" made available (e.g. a packaged v6.0.0 releases).
However, the node.js maintainers see "LTS" as more of a release phase than a version type. While they intend for minor/patch releases made when a major branch is in its active improvement (see "CURRENT" below) phase to be stable and backwards compatible, in the real world they might make mistakes.
So they divide development into three distinct phases:
CURRENT: new features (and bug fixes and security patches)
ACTIVE LTS: bug fixes (and security patches)
MAINTENANCE: only security patches
Odd-numbered major versions get only the first phase before being left behind. Even-numbered major versions — the ones we're mostly concerned about here — go through all three phases.
The CURRENT phase starts with the first public release, and starts the clock ticking on the 30-month support window. They may add significant new features, which should in theory be backwards-compatible but in practice may turn up some issues (new bug gets added, change made to poorly-defined behavior, they fix an old bug you had worked around poorly, etc.)
Then at some point the team decides to move the main development effort to a short-lived odd-numbered major branch (presumably when they need to intentionally break backwards compatibility). At that point the even-numbered branch moves to ACTIVE LTS and they get much more careful with the changes they make: primarily just bug fixes. So if you really want stability, this is the time to get "on board" with a particular release.
Eventually it moves even further to the MAINTENANCE phase, where the code is touched only in response to the most critical bugs (think: security patches). But by then there's probably a new release in LTS "phase" already.
So the choice on the homepage right now is between two even-numbered branches, "v4.4.5 LTS" and "v6.2.0 current". If the newer branch were odd-numbered then it would not be a good candidate for a production deploy where long-term support is desired.
My actual options are a bit more complex even:
I could simply stay on v0.10 which will get critical fixes until October. Or bump up to v0.12 to get those until the end of the year. But neither one of those gains me much, and so I'll rule them out.
I can deploy v4.4.5 which will is still getting general bug fixes right now, and will get security fixes for quite a while yet. This should give me the most stable install. The support cycle is getting to be halfway over already, though — and when it runs out I'll have missed this opportunity now to catch up with some of the major changes that have already happened in v5 and v6.
I am leaning towards deploying v6.2.0, assuming all my dependencies support it right now. This not only buys me a year longer term of "lifecyle remaining", but also gets me fully caught up with any breaking changes that were introduced between v0.10 and now. (It also gets me access to any useful new features — but in this case I don't have a chance to take advantage of it.) The risk I take is that when I update to any hypothetical v6.2.1 or v6.3.0 or beyond that comes along, it might accidentally yield some bad surprises.
In my case I'd rather deal now with the major intentional changes that v5 and v6 have already introduced, and then hopefully be all set (or at least only minor pain) from now all the way until April 2019.