From 2f3cb75b6ab55e2151dbfdab5e94c613beef0bea Mon Sep 17 00:00:00 2001 From: Joe Niland Date: Fri, 21 Aug 2026 13:54:33 +1000 Subject: [PATCH 1/3] doc: clarifications re: min tf/provider versions --- docs/community/contribute/faq.mdx | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/community/contribute/faq.mdx b/docs/community/contribute/faq.mdx index 225fed071..988914d69 100644 --- a/docs/community/contribute/faq.mdx +++ b/docs/community/contribute/faq.mdx @@ -90,16 +90,22 @@ 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 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. A major version bump of Terraform or a provider requires a major version bump of the module. + +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. From c1bcf07509e5c6d3a29a37c6c3b1add9c248dfb9 Mon Sep 17 00:00:00 2001 From: Joe Niland Date: Mon, 24 Aug 2026 10:58:34 +1000 Subject: [PATCH 2/3] doc: add clarification for pre 1.0 Clarify that provider/tf major version updates don't necessarily trigger a module major version update when the module is pre 1.0. --- docs/community/contribute/faq.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/community/contribute/faq.mdx b/docs/community/contribute/faq.mdx index 988914d69..b35e95922 100644 --- a/docs/community/contribute/faq.mdx +++ b/docs/community/contribute/faq.mdx @@ -90,7 +90,7 @@ 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 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 had a `0.x` version from its initial release on July 28, 2014 until the `1.0` release on June 8, 2021. @@ -104,6 +104,8 @@ we allow the greatest number of users to benefit from the work we do. If we brea We regularly need to bump these versions to take advantage of newer language features or resources. A major version bump of Terraform or a provider 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? From e656c18a48311eb3dcd8ee994b0c836c3d3ebd04 Mon Sep 17 00:00:00 2001 From: Joe Niland Date: Tue, 25 Aug 2026 10:12:42 +1000 Subject: [PATCH 3/3] Update docs/community/contribute/faq.mdx Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- docs/community/contribute/faq.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/community/contribute/faq.mdx b/docs/community/contribute/faq.mdx index b35e95922..ec47a63f9 100644 --- a/docs/community/contribute/faq.mdx +++ b/docs/community/contribute/faq.mdx @@ -102,7 +102,7 @@ we allow the greatest number of users to benefit from the work we do. If we brea ## 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. A major version bump of Terraform or a provider requires a major version bump of the 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.