Add technical blog post for provenance tracking feature#1635
Conversation
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
📝 WalkthroughWalkthroughAdds a new blog page documenting Atmos configuration provenance tracking and the Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant CLI as atmos CLI
participant Describe as describe component
participant Prov as provenance extractor
participant Renderer as output renderer
User->>CLI: run `atmos describe component --provenance`
CLI->>Describe: invoke describe component
Describe->>Prov: gather values + provenance (file, line, col, import depth)
Prov--)Renderer: provenance metadata + values
Renderer->>User: render TTY (ANSI, inline symbols, color by depth) or
Renderer->>User: emit non-TTY YAML/JSON with `__atmos_provenance`
note right of Renderer: Renderer chooses format based on TTY detection
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Disabled knowledge base sources:
📒 Files selected for processing (1)
🧰 Additional context used📓 Path-based instructions (1)website/**📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)
Files:
🪛 LanguageToolwebsite/blog/2025-10-15-provenance-tracking.mdx[typographical] ~18-~18: Consider using a typographic opening quote here. (EN_QUOTES) [grammar] ~18-~18: There might be a mistake here. (QB_NEW_EN) [typographical] ~50-~50: Consider using a typographic opening quote here. (EN_QUOTES) [typographical] ~50-~50: Consider using a typographic close quote here. (EN_QUOTES) [grammar] ~134-~134: There might be a mistake here. (QB_NEW_EN) [grammar] ~135-~135: There might be a mistake here. (QB_NEW_EN) [grammar] ~136-~136: There might be a mistake here. (QB_NEW_EN) [grammar] ~137-~137: There might be a mistake here. (QB_NEW_EN) [grammar] ~140-~140: There might be a mistake here. (QB_NEW_EN) [grammar] ~141-~141: There might be a mistake here. (QB_NEW_EN) [grammar] ~142-~142: There might be a mistake here. (QB_NEW_EN) [grammar] ~143-~143: There might be a mistake here. (QB_NEW_EN) [typographical] ~150-~150: Consider using a typographic opening quote here. (EN_QUOTES) [typographical] ~150-~150: Consider using a typographic opening quote here. (EN_QUOTES) [typographical] ~150-~150: Consider using a typographic close quote here. (EN_QUOTES) [style] ~154-~154: ‘merge together’ might be wordy. Consider a shorter alternative. (EN_WORDINESS_PREMIUM_MERGE_TOGETHER) [grammar] ~182-~182: There might be a mistake here. (QB_NEW_EN) [grammar] ~189-~189: There might be a mistake here. (QB_NEW_EN) ⏰ 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). (7)
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 |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #1635 +/- ##
==========================================
+ Coverage 64.97% 65.00% +0.03%
==========================================
Files 338 338
Lines 37535 37535
==========================================
+ Hits 24388 24401 +13
+ Misses 11201 11186 -15
- Partials 1946 1948 +2
Flags with carried forward coverage won't be shown. Click here to find out more. 🚀 New features to boost your workflow:
|
- Remove JSON Format Support section as requested - Fix use case examples to use grep instead of --query flag - Clarify that --query and --provenance don't work well together - Update Get Started section with accurate examples 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
- Delete "Comparison with sources" section to focus on the feature itself - Rewrite "How It Works" in plain language describing the tracking process - Explain step-by-step: reading YAML, tracking imports, merging configs, annotating output - Remove technical implementation details (API names, interfaces) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (5)
website/blog/2025-10-15-provenance-tracking.mdx (5)
41-41: Unify terminology: “current stack” vs “parent stack”The legend, symbols, and example text mix “parent stack” with “current stack”. Use one term.
-# ● [1] Defined in parent stack +# ● [1] Defined in current stack-- **● (black circle)** - Defined in the parent stack `[1]` +- **● (black circle)** - Defined in the current stack `[1]`-Instantly see that the CIDR is defined in the parent stack at line 10. No more guessing. +Instantly see that the CIDR is defined in the current stack at line 10. No more guessing.Also applies to: 61-61, 86-86
154-154: Qualify performance claim or cite source“Less than 10%” needs a source or softer wording (“lightweight”). Link to a benchmark if available.
24-25: Add cross‑link to “sources” docsSince you contrast with sources, link to that section/page for context.
170-172: Consider a JSON exampleAdd a small JSON snippet showing how provenance metadata is represented (key name, shape), after “--format json”.
150-150: Tighten phrasingMinor style nit.
-As configurations merge together—when a child stack overrides a parent's value, or when imports stack on top of each other—Atmos remembers each step. +As configurations merge—when a child stack overrides a parent's value, or when imports stack on top of each other—Atmos remembers each step.
📜 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)
website/blog/2025-10-15-provenance-tracking.mdx(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
website/**
📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)
website/**: Update website documentation in website/ when adding features
Ensure consistency between CLI help text and website documentation
Follow the website's documentation structure and style
Keep website code in website/ and follow its architecture/style; test changes locally
Keep CLI and website documentation in sync; document new features with examples and use cases
Files:
website/blog/2025-10-15-provenance-tracking.mdx
🪛 LanguageTool
website/blog/2025-10-15-provenance-tracking.mdx
[typographical] ~18-~18: Consider using a typographic opening quote here.
Context: ...ly, if you saw an unexpected value like cidr: "10.100.0.0/16", you'd have to: - Mental...
(EN_QUOTES)
[grammar] ~18-~18: There might be a mistake here.
Context: ... cidr: "10.100.0.0/16", you'd have to: - Mentally trace through import chains - O...
(QB_NEW_EN)
[typographical] ~50-~50: Consider using a typographic opening quote here.
Context: ...[3] catalog/vpc/defaults.yaml:8 cidr: "10.100.0.0/16" ...
(EN_QUOTES)
[typographical] ~50-~50: Consider using a typographic close quote here.
Context: ...c/defaults.yaml:8 cidr: "10.100.0.0/16" # ● [1] orgs/...
(EN_QUOTES)
[grammar] ~130-~130: There might be a mistake here.
Context: ...nment: On TTY (interactive terminal): - Two-column side-by-side layout (Configur...
(QB_NEW_EN)
[grammar] ~131-~131: There might be a mistake here.
Context: ...side layout (Configuration │ Provenance) - Color-coded depth indicators - Syntax hi...
(QB_NEW_EN)
[grammar] ~132-~132: There might be a mistake here.
Context: ...ovenance) - Color-coded depth indicators - Syntax highlighting - Visual symbols **...
(QB_NEW_EN)
[grammar] ~133-~133: There might be a mistake here.
Context: ...d depth indicators - Syntax highlighting - Visual symbols **Non-TTY (pipes, CI/CD)...
(QB_NEW_EN)
[grammar] ~136-~136: There might be a mistake here.
Context: ...isual symbols Non-TTY (pipes, CI/CD): - Single-column layout (preserves valid YA...
(QB_NEW_EN)
[grammar] ~137-~137: There might be a mistake here.
Context: ...gle-column layout (preserves valid YAML) - Inline comments without color codes - Pl...
(QB_NEW_EN)
[grammar] ~138-~138: There might be a mistake here.
Context: ...L) - Inline comments without color codes - Plain text symbols - Optimized for scrip...
(QB_NEW_EN)
[grammar] ~139-~139: There might be a mistake here.
Context: ...without color codes - Plain text symbols - Optimized for scripting ## How It Works...
(QB_NEW_EN)
[typographical] ~146-~146: Consider using a typographic opening quote here.
Context: ...t encounters. When it reads a line like cidr: "10.100.0.0/16" from `orgs/acme/prod/us-...
(EN_QUOTES)
[typographical] ~146-~146: Consider using a typographic opening quote here.
Context: .../acme/prod/us-east-2.yaml`, it records: "I saw this value at line 10, column 3 in...
(EN_QUOTES)
[typographical] ~146-~146: Consider using a typographic close quote here.
Context: ...value at line 10, column 3 in this file." When Atmos imports another file, it re...
(EN_QUOTES)
[style] ~150-~150: ‘merge together’ might be wordy. Consider a shorter alternative.
Context: ...in the import chain. As configurations merge together—when a child stack overrides a parent's...
(EN_WORDINESS_PREMIUM_MERGE_TOGETHER)
[grammar] ~178-~178: There might be a mistake here.
Context: ...n extensible interface that will enable: - atmos.yaml provenance - Track where At...
(QB_NEW_EN)
[grammar] ~185-~185: There might be a mistake here.
Context: ...) or open an issue if you find any bugs.
(QB_NEW_EN)
⏰ 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). (4)
- GitHub Check: Build (windows-latest, windows)
- GitHub Check: Analyze (go)
- GitHub Check: website-deploy-preview
- GitHub Check: Summary
🔇 Additional comments (3)
website/blog/2025-10-15-provenance-tracking.mdx (3)
70-75: Verify color mapping matches CLI outputConfirm the actual colors used by the CLI for depth indicators; update if they differ.
Do you want me to sync this with the CLI help/implementation?
8-8: Confirm Terminal component pathEnsure @site/src/components/Terminal exists and supports fenced code blocks inside.
160-172: Both flags are supported and consistently documented.The
--fileand--format jsonflags are fully supported byatmos describe componentand documented consistently across the codebase:
- CLI help (
website/src/components/Screengrabs/atmos-describe-component--help.html): Shows both flags with examples- Reference docs (
website/docs/cli/commands/describe/describe-component.mdx): Includes examples and detailed flag descriptions- Your blog snippet matches the documented syntax exactly
- Add note explaining --query flag doesn't work with --provenance - Recommend using grep/yq/jq to filter provenance output instead - Keep existing grep examples in use cases 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
71de36d to
b56472a
Compare
- Change {/* truncate */} to <!--truncate-->
- This ensures Docusaurus generates blog excerpts correctly
Addresses CodeRabbit review comment.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
|
These changes were released in v1.195.0-test.0. |
what
sourcessystem/cli/commands/describe/componentwhy
--provenanceflag feature that users have been requestingreferences
--provenanceflag toatmos describe component#1584 (original provenance implementation)Summary by CodeRabbit