Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 10 additions & 2 deletions docs/community/contribute/faq.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Comment thread
joe-niland marked this conversation as resolved.

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.
Expand Down
Loading