Terraform: Please respect semantic versioning

[RyanCopley]

https://github.com/hashicorp/terraform/blob/master/CHANGELOG.md#0100-august-2-2017

We were previously using 0.9.6, and one of our team members upgraded to 0.10.0 thinking it would be safe. However, 0.9.6 to 0.10.0 has backwards incompatibility issues. Semantic versioning helps with this, as defined here: http://semver.org/

MAJOR version when you make incompatible API changes

This is indicated by increasing the first number in the 3 number version string. This is very important to the community as it is how we understand if we can upgrade safely.

[kshep]

semver.org also states:

Version 1.0.0 defines the public API. The way in which the version number is incremented after this release is dependent on this public API and how it changes.

While I cringe a little at the practice of keeping things in 0.x.x status for years, it's definitely an indication to the community we need to be prepared for breaking changes in the API with any release, no matter how minor.

[apparentlymart]

Hi @RyanCopley, @kshep,

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.

[RyanCopley]

Fair enough

[kylie-sre]

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.

@apparentlymart You have an enterprise offering and you still haven't gone to 1.0 and still don't respect SemVer. These is causing havoc within our TF files as well as terraform enterprise. Files written for 0.11.x aren't compatible with 0.12.x. They aren't even compatible between the same minor version in all cases.

[hashibot[bot]]

I'm going to lock this issue because it has been closed for _30 days_ ⏳. This helps our maintainers find and focus on the active issues.

If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.