Skip to content

docs: make versioning labels and breaking changes prescriptive - #929

Open
Erik Osterman (Cloud Posse) (osterman) wants to merge 3 commits into
masterfrom
docs/prescriptive-versioning-labels
Open

Erik Osterman (Cloud Posse) (osterman) wants to merge 3 commits into
masterfrom
docs/prescriptive-versioning-labels

Conversation

@osterman

@osterman Erik Osterman (Cloud Posse) (osterman) commented Oct 16, 2026 •

Copy link
Copy Markdown
Member

what

  • Replace the versioning strategy section with a label table: major, minor, patch, no-release. Maintainers must apply exactly one label.
  • Add "What is a breaking change?" with 7 rules for modules at 1.0 or higher. This includes raising any minimum Terraform or provider version (also within the same major version) and provider major upgrades.
  • Add non-breaking alternatives: variables-deprecated.tf fallback, moved blocks, new variables that keep old behavior.
  • Keep the rationale in a new "Why do we release this way?" section: release on every merge, users pin versions, every change is breaking for somebody. Keep the 0.x burn-in explanation.
  • Move the 0.x exception and the "raise minimum versions only for a reason" guidance from doc: clarifications re: min tf/provider versions #927 into their own sections.
  • Change the merge section so it refers to labels, not to manual version bumps.

why

  • The old text said majors are "milestone-driven", but CONTRIBUTING.md and our practice use major for breaking changes. Reviewers could not apply both. The milestone-driven wording is removed.
  • doc: clarifications re: min tf/provider versions #927 added the minimum-version rule but did not name the labels.
  • Reviewers need one prescriptive source for which label to apply.

references

🤖 Generated with Claude Code

https://claude.ai/code/session_01JW9Go7ujHrXLWGtnmbgynt

@coderabbitai

coderabbitai Bot commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration
  • Configuration used: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 41bed23f-ad8b-4222-a175-16ae319406a6

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration
  • Configuration used: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 8c811803-6781-41bf-b0f0-dbeb0d7ac0bc
📥 Commits

Reviewing files that changed from the base of the PR and between fdf4e44 and 8d097ad.

📒 Files selected for processing: 1
  • docs/community/contribute/faq.mdx

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

📝 Walkthrough

The contribution FAQ now describes label-driven releases, versioning rules for modules, and release automation on merges to the default branch.

Changes: Release guidance

Layer / File(s) Summary
Versioning rules and release automation
docs/community/contribute/faq.mdx
The FAQ documents release labels, breaking-change guidance for 1.0+ and 0.x modules, and automated releases on each merge to master. It replaces manual release instructions and milestone-based examples.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 8d097

No confirmed release-guidance defect remains. The available docs-repository configuration does not establish incorrect behavior for module releases.

Pre-merge checks: Passed 5
Check name Status Explanation
Docstring Coverage Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Title check Passed The title clearly and concisely describes the main documentation change: making versioning labels and breaking-change rules prescriptive.
Description check Passed The description directly explains the changes to versioning labels, breaking-change rules, non-breaking alternatives, and merge guidance.
Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (1 skipped: 1 unsupported.)

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

| Label | Apply when |
| :----------- | :------------------------------------------------------------------------------------------ |
| `major` | The change can break an existing caller of a module at `1.0` or higher. See the rules below. |
| `minor` | The change adds a feature and does not change the plan for existing callers. Also, any change to a module that is still `0.x`. |

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Regarding any change - wouldn't patch releases still apply for the stated purposes, for pre 1.0 modules?

Perhaps that should be any major change if I'm understanding correctly?

This branch was successfully deployed

1 active deployment
preview — fa02c96e Deployed Oct 17, 2026 by osterman via deploy-preview #1313
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants