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.
Related
Let us say that I have worked on a haskell library and am now ready to release a beta version of the software to hackage/make repo public on github etc.
Possible Solutions and why they do not work for me
Use packagename-0.0.0.1-alpha or similar.
The problem here is quite simple: The Haskell PVP Specification does not allow it: (bold is me)
The components of the version number MUST be numbers! Historically Cabal supported version numbers with string tags at the end, e.g. 1.0-beta This proved not to work well because the ordering for tags was not well defined. Version tags are no longer supported and mostly ignored, however some tools will fail in some circumstances if they encounter them.
Just use packagename-0.* until it is out of alpha/beta (and then use packagename-1.*).
The problem here is twofold:
This method would not work for describing relase candidates which are post version 1.
Programmers from other ecosystems, such as that of rust, where it is quite common to have a stable library in 0.*, might wrongly assume that this library is stable. (Of course, it could be mitigated somewhat with a warning in the README, but I would prefer a better solution still.)
So, what is the best (and most conventional in haskell) way to indicate that the library version is in alpha/beta stage of development or is a release candidate?
As far as I know, there is not a package-wide way to say this. However, you can add a module description that describes the stability of the module to each of your modules' documentation.
{-|
Stability: experimental
-}
module PackageName.ModuleName where
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 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.
Murphy kicked my a$$ about an hour ago.
Context:
I recently joined a new employer and the product was quite outdated in terms of dependencies, Angular 1.2.x, Angular-UI 0.12.0, etc...
This is the first employer I've worked at that does daily builds to prod etc. (previosuly I've only worked in what can be called large corporate, with much slower turn around) Part of my initial task was to upgrade dependencies where I can. Thus earlier this morning we had a watercooler talk with some of the devs about why all of our bower dependencies are hardcoded to specific versions.
The 2 schools of thought are:
Hardcoding versions obviously gives 100% security as versions can't dynamically jump, but has the drawback that if someone doesnt actively update we'll fall behind again.
I'm of the opinion that semantic versioning gives us some form of security (coupled with having multiple staging environments), and that it should be good enough to, say, have Angular set to say ^1.5.9.
Quoted from the Semantic Version Docs:
Minor version Y (x.Y.z | x > 0) MUST be incremented if new, backwards
compatible functionality is introduced to the public API. It MUST be
incremented if any public API functionality is marked as deprecated.
It MAY be incremented if substantial new functionality or improvements
are introduced within the private code. It MAY include patch level
changes. Patch version MUST be reset to 0 when minor version is
incremented.
Problem:
Earlier this morning we deployed to staging, and everything seemed good to go, then we deployed to production an hour or so ago and ... BOOM
The issue was the AngularJs change from 1.5.9, to 1.6.0. I've seen in the migration docs (migrate 1.5 -> 1.6) that this has been noted:
You may also notice that this release comes with a longer-than-usual
list of breaking changes. Don't let this dishearten you though, since
most of them are pretty minor - often not expected to affect real
applications. These breaking changes were necessary in order to:
Question:
Where is my disconnect? ...or is the semantic version docs just a false sense of security I've had all along?
How do people out there in the handle these situations? Do people make use of auto dependency upgrading in any real world solutions (excuse me if this is super obvious to some), as to me, the fact that the build passed staging, and broke in production is actually more concerning.
(The reason I'm asking is because the fear of small incremental updates are now back and stronger than ever, and I'm not sure if I agree with the sentiment of it all...)
Seems pretty simple, if they make breaking changes, they should have bumped it up to 2.0.0. They are not doing semantic versioning. Not all projects using X.Y.Z. style versions are doing semantic versioning.
Try to catch how this went "boom" in an automated way in your testing and staging environments. Can't fear moving forward, it has to be done sometime, and I'd rather move step-by-step more frequently, than to suddendly move up many versions as would be done with an entirely manual process.
Cabal allows for a freeform Stability field:
stability: freeform
The stability level of the package, e.g. alpha, experimental, provisional, stable.
What are the community conventions about these stability values? What is considered experimental and what is provisional? I see only few packages are declared as stable. What kind of stability does it refer to, stability of the exposed API or the ultimate bug-free state of the software?
The field is mostly defunct now, and shouldn't be used. As Max said, it will probably be replaced by something meaningful in the future.
If you're interested in the history, the field originated in a design proposal for the first set of Hierarchical Haskell Libraries. That document describes the original intended meanings for the values.
Currently this field is a very poor guide to the stability of the library, so is mostly ignored. Duncan Coutts (one of the main Cabal and Hackage developers) has said that he eventually plans to replace this field entirely, with something like a social voting system on Hackage.
Personally (and I'm not alone) I just always omit the stability field. Given that it's going to go away, its probably not worth losing any sleep over what to put into it.
The original intended meanings were:
experimental: the API is unstable. It may change at any time, i.e.: any version number change;
provisional: the API is moving towards stability. It may be changed at every minor revision, but should provide deprecated versions of features;
stable: the API is stable. Only additions should be made at minor releases. After changes in the API, deprecated features should be kept for at least one major release.
As the other answers pointed out, the community seems not to be following these guidelines anymore.
As Simon Marlow points out, this is described in a design proposal for the first set of Hierarchical Haskell Libraries. The original link is dead, but you can find a copy in the wayback machine.