diff --git a/docs/community/contribute/faq.mdx b/docs/community/contribute/faq.mdx index 225fed071..ec47a63f9 100644 --- a/docs/community/contribute/faq.mdx +++ b/docs/community/contribute/faq.mdx @@ -90,16 +90,24 @@ Following this strategy allows us to move quickly, release often while enabling 1. **Patch Releases** We bump the patch release for bug fixes of *existing* functionality or small updates to documentation 2. **Minor Releases** Projects that are `< 1.x`, every merge to `master` else is a minor release. This is the proper [semver convention](https://semver.org/#spec-item-4) for `0.x.y` releases. - - While we always try to ensure the interfaces won't change radically, we cannot promise that will remain the case, especially when the tool itself (e.g. `terraform` is not yet `1.0`). + - While we always try to ensure the interfaces won't change radically, we cannot promise that will remain the case, especially when the tool (Terraform) itself is not yet `1.0`. - Once the interface is more or less guaranteed to be stable we will release a 1.0. 3. **Major Releases** The major version is milestone-driven (e.g. `> 1.x`). The first milestone is always stability. A major release will correspond to the previous minor release that closes out that milestone. - - The 1.0 milestone doesn’t happen until we have had a very long burn-in period where it is stable and the interface works. For comparison, the `terraform` language is still `0.x` since July 28, 2014. + - The 1.0 milestone doesn’t happen until we have had a very long burn-in period where it is stable and the interface works. For comparison, the `terraform` language had a `0.x` version from its initial release on July 28, 2014 until the `1.0` release on June 8, 2021. - **After 1.0** all major releases are driven by achieving a particular feature set A common strategy practiced by other organizations is to bump the major release when there's a “known breaking change” and usually includes many changes all at once. This is typically practiced post-1.0 and it's still somewhat arbitrary and difficult to verify. Philosophically speaking, every change is breaking for somebody. For example, if a project has a bug, chances are that someone has implemented a workaround for that bug. If we release a bug fix as a patch release, that could very well be a breaking change for anyone who had a workaround. By releasing frequently on every commit to `master`, we allow the greatest number of users to benefit from the work we do. If we break something, no big deal. Users should always practice strict version pinning - never using `master` directly. That way, users can just pin to the previous release of of a module. As a small organization managing *hundreds* of projects, attempting a formal release schedule for each project is not feasible. +## What impact does raising the minimum Terraform or provider version have on a module? + +We regularly need to bump these versions to take advantage of newer language features or resources. For modules at or above 1.0, raising the minimum required Terraform or provider version requires a major version bump of the module. + +**Note:** this rule does not apply to modules that are still `0.x`, which follow our normal pre-1.0 versioning strategy. + +Generally speaking, these upgrades should be done to harness a specific improvement and not solely to use the latest versions. + ## How do we create a new release? As a member of the `@cloudposse/contributors` team, create a new release, use the [built-in GitHub release functionality](https://help.github.com/en/enterprise/2.13/user/articles/creating-releases). Please do not create releases manually by creating tags and pushing them as this lacks all the metadata associated with a release, which can have a rich markdown description. All GitHub releases also have tags, but not all tags have a GitHub release.