docs: Add version constraint validation PRD #1759
Conversation
Add comprehensive Product Requirement Document for semantic version constraint validation feature. Allows atmos.yaml configurations to specify required Atmos version ranges using hashicorp/go-version library with configurable enforcement levels (fatal, warn, silent). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Dependency Review✅ No vulnerabilities or license issues found.Scanned FilesNone |
|
Warning Rate limit exceeded@osterman has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 2 minutes and 20 seconds before requesting another review. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📒 Files selected for processing (3)
📝 WalkthroughWalkthroughAdds a new product requirements document describing an Atmos version-constraint validation feature, including data model, semantics (enforcement modes), YAML examples, validation flow, schema proposal, implementation plan, and testing considerations. No code changes are included in this diff. Changes
Sequence Diagram(s)(omitted — diff contains documentation only; no control-flow code changes to visualize) Estimated code review effort🎯 1 (Trivial) | ⏱️ ~2 minutes
Suggested labels
Suggested reviewers
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
docs/prd/version-constraint.md (2)
108-115: Add language identifiers to code/output blocks for clarity.Several fenced code blocks lack language specifiers. For error/warning message blocks (lines 108–115, 129–135, 503–512, 515–523, 526–532), use
```textto properly render. Line 536–552 is a diagram/flow, which could use```textas well. This improves IDE syntax highlighting and markdown linting compliance.Examples:
- ``` + ```text ✗ Atmos version constraint not satisfied ...Also applies to: 129-135, 503-532, 536-552
208-208: Convert bare URL to markdown link.Line 208 has a bare URL. Convert it to a proper markdown link:
- Full syntax: https://github.com/hashicorp/go-version + Full syntax: [hashicorp/go-version](https://github.com/hashicorp/go-version)
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
docs/prd/version-constraint.md(1 hunks)
🧰 Additional context used
🧠 Learnings (3)
📓 Common learnings
Learnt from: Listener430
Repo: cloudposse/atmos PR: 934
File: tests/fixtures/scenarios/docs-generate/README.md.gotmpl:99-118
Timestamp: 2025-01-25T03:51:57.689Z
Learning: For the cloudposse/atmos repository, changes to template contents should be handled in dedicated PRs and are typically considered out of scope for PRs focused on other objectives.
Learnt from: aknysh
Repo: cloudposse/atmos PR: 944
File: go.mod:206-206
Timestamp: 2025-01-17T00:18:57.769Z
Learning: For indirect dependencies with license compliance issues in the cloudposse/atmos repository, the team prefers to handle them in follow-up PRs rather than blocking the current changes, as these issues often require deeper investigation of the dependency tree.
Learnt from: osterman
Repo: cloudposse/atmos PR: 801
File: examples/quick-start-advanced/Dockerfile:9-9
Timestamp: 2024-11-23T00:13:22.004Z
Learning: When updating the `ATMOS_VERSION` in Dockerfiles, the team prefers to pin to the next future version when the PR merges, even if the version is not yet released.
Learnt from: samtholiya
Repo: cloudposse/atmos PR: 1466
File: cmd/markdown/atmos_toolchain_aliases.md:2-4
Timestamp: 2025-09-13T16:39:20.007Z
Learning: In the cloudposse/atmos repository, CLI documentation files in cmd/markdown/ follow a specific format that uses " $ atmos command" (with leading space and dollar sign prompt) in code blocks. This is the established project convention and should not be changed to comply with standard markdownlint rules MD040 and MD014.
📚 Learning: 2025-07-05T20:59:02.914Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 1363
File: internal/exec/template_utils.go:18-18
Timestamp: 2025-07-05T20:59:02.914Z
Learning: In the Atmos project, gomplate v4 is imported with a blank import (`_ "github.com/hairyhenderson/gomplate/v4"`) alongside v3 imports to resolve AWS SDK version conflicts. V3 uses older AWS SDK versions that conflict with newer AWS modules used by Atmos. A full migration to v4 requires extensive refactoring due to API changes and should be handled in a separate PR.
Applied to files:
docs/prd/version-constraint.md
📚 Learning: 2024-12-02T21:26:32.337Z
Learnt from: osterman
Repo: cloudposse/atmos PR: 808
File: pkg/config/config.go:478-483
Timestamp: 2024-12-02T21:26:32.337Z
Learning: In the 'atmos' project, when reviewing Go code like `pkg/config/config.go`, avoid suggesting file size checks after downloading remote configs if such checks aren't implemented elsewhere in the codebase.
Applied to files:
docs/prd/version-constraint.md
🪛 LanguageTool
docs/prd/version-constraint.md
[grammar] ~11-~11: Use a hyphen to join words.
Context: ...State Currently, Atmos provides version checking functionality under the `versio...
(QB_NEW_EN_HYPHEN)
[typographical] ~233-~233: Consider using a typographic close quote here.
Context: ...ementinatmos.yaml3. Default value"fatal"` (lowest) ## Implementation Plan...
(EN_QUOTES)
[typographical] ~568-~568: Consider using typographic quotation marks here.
Context: ...rsion.constraint.require` is treated as "no constraint" - Default enforcement is "fatal" for sa...
(EN_QUOTES)
[typographical] ~569-~569: Consider using typographic quotation marks here.
Context: ...no constraint" - Default enforcement is "fatal" for safety, but can be explicitly set t...
(EN_QUOTES)
[typographical] ~569-~569: Consider using typographic quotation marks here.
Context: ...or safety, but can be explicitly set to "warn" ## Security Considerations - Version ...
(EN_QUOTES)
🪛 markdownlint-cli2 (0.18.1)
docs/prd/version-constraint.md
108-108: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
129-129: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
208-208: Bare URL used
(MD034, no-bare-urls)
503-503: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
515-515: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
526-526: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
536-536: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
619-619: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (8)
- GitHub Check: Build (macos)
- GitHub Check: Build (windows)
- GitHub Check: Run pre-commit hooks
- GitHub Check: Analyze (go)
- GitHub Check: Lint (golangci)
- GitHub Check: Review Dependency Licenses
- GitHub Check: autofix
- GitHub Check: Summary
🔇 Additional comments (2)
docs/prd/version-constraint.md (2)
1-100: Excellent PRD—clear problem, solid design, and thorough planning.This is a well-structured requirements document. The problem statement is articulate, the design decisions are justified (especially the choice of string format and hashicorp/go-version reuse), and the 7 configuration examples cover realistic scenarios. The implementation plan is detailed enough to guide development, and the backward-compatibility guarantee is reassuring.
100-250: Validate environment override precedence against Atmos conventions.The
ATMOS_VERSION_ENFORCEMENToverride precedence (env var > config > default) is sensible, but it's worth verifying this pattern aligns with how Atmos handles other environment-based configuration overrides elsewhere in the codebase to keep behavior predictable.
…on list concerns Add comprehensive problem statements addressing real-world challenges: - Multi-environment version drift (CI, local, containers) - Silent feature unavailability in older versions - Experimentation friction without proper warnings Add new configuration examples: - Multi-environment consistency enforcement - Experimentation mode with warnings for unsupported versions Add Phase 3 proposal for constraint-aware version listing: - Optional --constraint-aware flag for atmos version list - Filters releases based on version.constraint.require - Three design options with recommendation for flag-based approach - Future enhancement: warnings for versions outside constraints 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (7)
docs/prd/version-constraint.md (7)
3-33: Excellent problem framing—clear motivation for the feature.The problem statement does a strong job articulating real challenges teams face (multi-environment drift, feature gating, breaking changes). The existing
version.checkcontext helps orient readers to what's already available.Minor: Line 11 grammar—consider hyphenating: "version-checking functionality" per the static analysis flag.
100-228: Comprehensive and realistic examples.The nine examples effectively demonstrate the feature's flexibility, progressing naturally from simple minimum-version constraints through multi-constraint scenarios and experimentation modes. The multi-line custom messages in Examples 6, 7, and 8 show practical team adoption patterns.
Minor formatting: Lines 111 and 132 (error output examples) lack language tags—add
bash ortext to comply with MD040.
230-271: Clear reference and sensible override hierarchy.The syntax table covers all supported operators, and the precedence order for enforcement (env var > config > default) is both sensible and well-explained. Good thought on allowing runtime overrides for CI/debugging scenarios.
Line 246: Wrap the bare URL in markdown link syntax—
[go-version](https://github.com/hashicorp/go-version)per MD034.
273-561: Implementation plan is detailed, phased, and realistic.Phase 1 provides concrete file locations, Go code patterns, and test cases. The validation logic properly handles enforcement levels and error cases. Phase 2 scope is appropriately scoped to documentation. Phase 3 thoughtfully analyzes design options before recommending the flag-based approach.
The ValidateConstraint function and integration in initConfig are straightforward. Test coverage examples show good edge-case thinking (empty constraints, ranges, pessimistic constraints, invalid syntax).
Formatting: Add
golanguage tags to code blocks (lines 280–290, 294–321, 325–426, 430–500) for syntax highlighting consistency—though this is minor and won't affect implementation.
663-715: User-facing messaging is clear and helpful.Error messages include visual indicators, structured data (Required/Current versions), and actionable next steps (upgrade link, support contact). The validation flow diagram clearly shows the decision tree including early exit for invalid syntax constraints.
Formatting: Lines 666, 678, 689, 699 (error message blocks) should specify language—
bashortext—for syntax highlighting.
717-820: Thorough coverage of non-functional concerns and design rationale.Testing strategy has clear coverage target. Security and performance sections appropriately address offline-safety and minimal overhead. The dependencies section convincingly argues for reusing
hashicorp/go-version(already present, Terraform-compatible, zero new dependencies).The design rationale comparing string vs. list format is particularly well-articulated and includes library evidence showing native comma-separated parsing support.
Formatting: Lines 631, 637, 643, 782 use emphasis (Option 1, Option 2, etc.) instead of markdown headings. Consider converting to
### Option 1: Flag-based (RECOMMENDED)format for better semantic structure per MD036.Static analysis also flagged typographical quote suggestions in several places (straight quotes vs. smart quotes). While minor and often a matter of style, consider standardizing if the project has a quote convention.
1-820: Comprehensive, well-reasoned PRD ready for implementation planning.This PRD effectively specifies a version constraint validation feature that addresses real operational challenges. The design is conservative (fully backward-compatible, reuses existing dependency), the examples are practical, and the three-phase implementation plan is realistic. The feature elegantly extends the existing
versionconfig without breaking changes.Strong aspects:
- Solid design choices: String format constraints match Terraform semantics and leverage library native support
- Enforcement hierarchy (fatal → warn → silent) provides appropriate flexibility
- Environment variable override enables debugging without config changes
- Comprehensive examples from minimum versions to multi-environment consistency
- Phased approach defers optional enhancements (Phase 3) appropriately
Minor observations for "Chill" mode (all optional):
- Markdown linting: Add language tags to code blocks (lines 111, 132, 280–290, 294–321, 325–426, 430–500, 666, 678, 689, 699)
- Markdown structure: Convert emphasis-styled options to
### Headingformat for better semantics- Bare URL: Wrap line 246 URL in markdown link syntax
- Grammar: Line 11 — consider hyphenating "version-checking"
- Quotes: Various lines use straight quotes; if the project standardizes on smart quotes, apply consistently
Ready to implement Phase 1 core validation and integration.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
docs/prd/version-constraint.md(1 hunks)
🧰 Additional context used
🧠 Learnings (3)
📓 Common learnings
Learnt from: Listener430
Repo: cloudposse/atmos PR: 934
File: tests/fixtures/scenarios/docs-generate/README.md.gotmpl:99-118
Timestamp: 2025-01-25T03:51:57.689Z
Learning: For the cloudposse/atmos repository, changes to template contents should be handled in dedicated PRs and are typically considered out of scope for PRs focused on other objectives.
Learnt from: aknysh
Repo: cloudposse/atmos PR: 944
File: go.mod:206-206
Timestamp: 2025-01-17T00:18:57.769Z
Learning: For indirect dependencies with license compliance issues in the cloudposse/atmos repository, the team prefers to handle them in follow-up PRs rather than blocking the current changes, as these issues often require deeper investigation of the dependency tree.
Learnt from: osterman
Repo: cloudposse/atmos PR: 801
File: examples/quick-start-advanced/Dockerfile:9-9
Timestamp: 2024-11-23T00:13:22.004Z
Learning: When updating the `ATMOS_VERSION` in Dockerfiles, the team prefers to pin to the next future version when the PR merges, even if the version is not yet released.
Learnt from: samtholiya
Repo: cloudposse/atmos PR: 1466
File: cmd/markdown/atmos_toolchain_aliases.md:2-4
Timestamp: 2025-09-13T16:39:20.007Z
Learning: In the cloudposse/atmos repository, CLI documentation files in cmd/markdown/ follow a specific format that uses " $ atmos command" (with leading space and dollar sign prompt) in code blocks. This is the established project convention and should not be changed to comply with standard markdownlint rules MD040 and MD014.
📚 Learning: 2025-09-13T16:39:20.007Z
Learnt from: samtholiya
Repo: cloudposse/atmos PR: 1466
File: cmd/markdown/atmos_toolchain_aliases.md:2-4
Timestamp: 2025-09-13T16:39:20.007Z
Learning: In the cloudposse/atmos repository, CLI documentation files in cmd/markdown/ follow a specific format that uses " $ atmos command" (with leading space and dollar sign prompt) in code blocks. This is the established project convention and should not be changed to comply with standard markdownlint rules MD040 and MD014.
Applied to files:
docs/prd/version-constraint.md
📚 Learning: 2025-07-05T20:59:02.914Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 1363
File: internal/exec/template_utils.go:18-18
Timestamp: 2025-07-05T20:59:02.914Z
Learning: In the Atmos project, gomplate v4 is imported with a blank import (`_ "github.com/hairyhenderson/gomplate/v4"`) alongside v3 imports to resolve AWS SDK version conflicts. V3 uses older AWS SDK versions that conflict with newer AWS modules used by Atmos. A full migration to v4 requires extensive refactoring due to API changes and should be handled in a separate PR.
Applied to files:
docs/prd/version-constraint.md
🪛 LanguageTool
docs/prd/version-constraint.md
[grammar] ~11-~11: Use a hyphen to join words.
Context: ...State Currently, Atmos provides version checking functionality under the `versio...
(QB_NEW_EN_HYPHEN)
[typographical] ~271-~271: Consider using a typographic close quote here.
Context: ...ementinatmos.yaml3. Default value"fatal"` (lowest) ## Implementation Plan...
(EN_QUOTES)
[typographical] ~641-~641: Consider using typographic quotation marks here.
Context: ... Con: Confusing if constraint is set to "warn" enforcement **Option 3: Auto-enable wh...
(EN_QUOTES)
[typographical] ~643-~643: Consider using typographic quotation marks here.
Context: ...o-enable when constraint enforcement is "fatal"** - Pro: Smart default based on enforce...
(EN_QUOTES)
[typographical] ~731-~731: Consider using typographic quotation marks here.
Context: ...rsion.constraint.require` is treated as "no constraint" - Default enforcement is "fatal" for sa...
(EN_QUOTES)
[typographical] ~732-~732: Consider using typographic quotation marks here.
Context: ...no constraint" - Default enforcement is "fatal" for safety, but can be explicitly set t...
(EN_QUOTES)
[typographical] ~732-~732: Consider using typographic quotation marks here.
Context: ...or safety, but can be explicitly set to "warn" ## Security Considerations - Version ...
(EN_QUOTES)
🪛 markdownlint-cli2 (0.18.1)
docs/prd/version-constraint.md
111-111: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
132-132: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
246-246: Bare URL used
(MD034, no-bare-urls)
631-631: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
637-637: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
643-643: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
666-666: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
678-678: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
689-689: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
699-699: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
782-782: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (8)
- GitHub Check: Build (windows)
- GitHub Check: Build (macos)
- GitHub Check: Analyze (go)
- GitHub Check: Lint (golangci)
- GitHub Check: autofix
- GitHub Check: Run pre-commit hooks
- GitHub Check: Review Dependency Licenses
- GitHub Check: Summary
🔇 Additional comments (1)
docs/prd/version-constraint.md (1)
35-96: Well-designed data model with strong rationale.The YAML structure is clean, the Go struct properly tagged, and the design choice for string-format constraints (vs. list) is justified convincingly (Terraform parity, library native support, simpler YAML). The comment examples in the struct definition are particularly helpful.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #1759 +/- ##
=======================================
Coverage 72.07% 72.07%
=======================================
Files 474 474
Lines 45521 45521
=======================================
+ Hits 32807 32810 +3
- Misses 10095 10096 +1
+ Partials 2619 2615 -4
Flags with carried forward coverage won't be shown. Click here to find out more. 🚀 New features to boost your workflow:
|
osterman
added
the
no-release
Add ability to enforce Atmos version requirements in atmos.yaml configuration. Teams can now ensure consistent Atmos versions across developers and CI/CD. Configuration: - version.constraint.require: semver constraint (e.g., ">=1.100.0, <2.0.0") - version.constraint.enforcement: fatal|warn|silent (default: fatal) - version.constraint.message: custom error message - ATMOS_VERSION_ENFORCEMENT env var override Uses hashicorp/go-version library (already in go.mod) for Terraform-compatible constraint syntax including pessimistic operator (~>). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
github-actions
bot
added
size/xl
|
Warning This PR exceeds the recommended limit of 1,000 lines.Large PRs are difficult to review and may be rejected due to their size. Please verify that this PR does not address multiple issues. |
Summary
Add comprehensive Product Requirement Document for semantic version constraint validation feature, allowing
atmos.yamlconfigurations to specify required Atmos version ranges using thehashicorp/go-versionlibrary with configurable enforcement levels (fatal, warn, silent).What's Included
version.constraintconfiguration sectionhashicorp/go-versionlibraryKey Features
>=2.5.0,<3.0.0, ranges, pessimistic (~>2.5), exclusions (!=2.7.0)ATMOS_VERSION_ENFORCEMENTfor runtime controlhashicorp/go-versionv1.7.0🤖 Generated with Claude Code
Summary by CodeRabbit