Comprehensive Schema Enhancement and Deprecation Infrastructure

[osterman]

what

• Implement comprehensive schema validation and documentation system for all Atmos configuration files
• Add unified deprecation infrastructure with consistent warning messaging
• Create complete JSON schemas for CLI, Stack, Workflow, and Vendor configurations
• Provide comprehensive example files showcasing all configuration options
• Update documentation to include interactive schema viewers and examples
• Add support for new color terminal setting while maintaining backward compatibility

why

• Improved Developer Experience: Comprehensive schemas enable IDE autocompletion, validation, and inline documentation
• Better Documentation: Interactive schema viewers and complete examples help users understand all available options
• Consistent Deprecation Handling: Unified deprecation warnings provide clear migration paths for deprecated features
• Future-Proof Configuration: New color field replaces no_color with proper boolean semantics
• Validation Support: JSON schemas enable validation tools and CI/CD integration
• Comprehensive Coverage: All configuration types now have complete schema documentation

Implementation Details

Deprecation Infrastructure

• Created NotifyDeprecatedField utility for consistent deprecation warnings across the codebase
• Standardized message format: `old.path` is deprecated; use `new.path` instead
• Updated existing deprecations in cmd/docs.go to use new utility function
• Backward compatibility maintained for ATMOS_NO_COLOR and deprecated settings

Schema Enhancements

• CLI Schema (cli.json): Added all missing root-level sections including version, aliases, stores, schemas, templates, integrations, complete settings with terminal, telemetry, pro configurations
• Stack Schema (stack.json): Added Packer component support with full component lifecycle definitions
• Workflow Schema (workflow.json): Added retry configuration with exponential backoff support (max_attempts, backoff_strategy, initial_delay, etc.)
• Vendor Schema: Verified completeness of vendoring manifest schema

Terminal Configuration Updates

• Added color field to Terminal struct as preferred replacement for no_color
• Environment variable support for ATMOS_COLOR while maintaining ATMOS_NO_COLOR compatibility
• Automatic migration logic converts no_color: true to color: false with deprecation warnings

Comprehensive Examples

• atmos.yaml: 322 lines showcasing all CLI configuration options with inline documentation and deprecation comments
• stack.yaml: 364 lines demonstrating Terraform, Helmfile, and Packer components with advanced features
• vendor.yaml: 296 lines showing various source types (GitHub, GitLab, S3, local) and configurations
• workflow.yaml: 363 lines with retry strategies, complex workflows, and real-world examples

Documentation Integration

• Interactive Schema Viewers: All schema documentation now includes JSONSchemaViewer components
• Complete Examples: Added comprehensive example files using <File> component for proper rendering
• Raw Loader Integration: Uses \!\!raw-loader\! for embedding YAML content in documentation

Technical Changes

Core Files Modified

• pkg/utils/deprecation.go - New deprecation utility function
• pkg/schema/schema.go - Added Color field to Terminal struct
• pkg/config/config.go - Added deprecation handling logic with automatic migration
• pkg/config/load.go - Added ATMOS_COLOR environment variable binding
• cmd/docs.go - Updated to use new deprecation function

Schema Files

• Complete rewrite of website/static/schemas/atmos/1.0/cli.json (727 lines)
• Enhanced website/static/schemas/atmos/1.0/stack.json with Packer support (822 lines)
• Updated website/static/schemas/atmos/1.0/workflow.json with retry configuration (88 lines)
• Verified website/static/schemas/atmos/1.0/vendor.json completeness (102 lines)

Example Files

• website/static/examples/schemas/atmos.yaml - Comprehensive CLI configuration example
• website/static/examples/schemas/stack.yaml - Complete stack manifest example
• website/static/examples/schemas/vendor.yaml - Vendor configuration with multiple source types
• website/static/examples/schemas/workflow.yaml - Advanced workflow configurations with retry

Documentation Updates

• website/docs/schemas/cli.mdx - Added interactive schema viewer and complete example
• website/docs/schemas/stack.mdx - Enhanced with comprehensive stack examples
• website/docs/schemas/vendor.mdx - Added vendoring examples and documentation
• website/docs/schemas/workflow.mdx - Added workflow examples with retry configurations

Testing & Validation

• ✅ Build successful - All code compiles without errors
• ✅ Deprecation warnings functional - Tested with deprecated no_color setting
• ✅ Backward compatibility verified - ATMOS_NO_COLOR environment variable still works
• ✅ Schema validation - All JSON schemas are valid and comprehensive
• ✅ Example files tested - All example configurations are syntactically correct

Migration Guide

For users with deprecated settings:

Replace no_color with color

# OLD (deprecated)
settings:
  terminal:
    no_color: true

# NEW (preferred)  
settings:
  terminal:
    color: false

Update docs settings

# OLD (deprecated)
settings:
  docs:
    max-width: 120
    pagination: true

# NEW (preferred)
settings:
  terminal:
    max_width: 120
    pager: true

Breaking Changes

None - all changes maintain backward compatibility with deprecation warnings.

references

• Closes schema validation and documentation gaps
• Enhances developer experience with comprehensive examples
• Implements unified deprecation strategy for future configuration changes
• Provides foundation for advanced IDE integration and validation tooling

Summary by CodeRabbit

• New Features

  • Added JSON Schemas (CLI, Stack, Vendor, Workflow) and a validation script to validate configs; reorganized LocalStack commands for clearer workflows.

• Breaking/Config Changes

  • Renamed public config keys: stacks.name_pattern → stacks.name_template; helmfile.cluster_name_pattern → cluster_name_template; spacelift/stack_name_pattern → stack_name_template.

• Documentation

  • New schema reference pages, "Complete Configuration Reference," many docs/examples updated to use name_template/cluster_name_template.

• Chores

  • CI job to verify schema checksums; added JSON Schema viewer plugin, sidebar entries, example schema files, and minor CSS tweaks.

[mergify[bot]]

[!IMPORTANT]

Cloud Posse Engineering Team Review Required

This pull request modifies files that require Cloud Posse's review. Please be patient, and a core maintainer will review your changes.

To expedite this process, reach out to us on Slack in the #pr-reviews channel.

[mergify[bot]]

[!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. Consider refactoring it into smaller, more focused PRs to facilitate a smoother review process.

[coderabbitai[bot]]

📝 Walkthrough

Walkthrough

Renames stack/cluster naming keys from pattern → template across code, tests, fixtures, and docs; adds JSON Schemas, schema docs/examples, a validation script, and a CI checksum job; introduces deprecation notifications and config migrations for terminal/docs settings; centralizes new error constants and updates callers.

Changes

Cohort / File(s)	Summary
CI & schema validation tooling .github/workflows/test.yml, validate-all-schemas.sh, SCHEMA_VALIDATION.md, docs/prd/atmos-schemas.md	Adds CI job to verify schema checksums, a shell script to validate YAML files against new JSON schemas, and documentation/PRD describing the validation system.
JSON Schemas (new) website/static/schemas/atmos/1.0/cli.json, .../stack.json, .../vendor.json, .../workflow.json	Adds CLI, Stack, Vendor, and Workflow JSON Schema files (draft 2020-12) with fileMatch and detailed property constraints.
Schema pages & site wiring website/docs/schemas/*.mdx, website/docusaurus.config.js, website/package.json, website/sidebars.js, website/src/css/custom.css, website/static/examples/schemas/*	Adds schema docs pages with JSONSchemaViewer, sample examples, adds docusaurus plugin dependency, sidebar entry, and CSS tweaks for viewer.
Manifest schema tweak (depends_on) examples/**/schemas/atmos-manifest.json, tests/fixtures/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json	Removes the stack property from depends_on_manifest in multiple manifest schema examples.
Global rename: stacks.name_pattern → stacks.name_template examples/**/atmos.yaml, tests/fixtures/**/atmos.yaml, pkg/**/atmos.yaml, website/docs/**, website/src/components/Screengrabs/**, examples/demo-stacks/component.yaml, tests/snapshots/*.golden	Renames configuration key across code, examples, fixtures, docs and updates example values to Go-template form where applied.
Helmfile rename: cluster_name_pattern → cluster_name_template pkg/**/atmos.yaml, pkg/schema/schema.go, tests/fixtures/**/helmfile.yml, website/docs/**	Renames Helmfile cluster naming field and updates struct tags/docs/fixtures.
Spacelift rename: stack_name_pattern → stack_name_template internal/exec/spacelift_utils.go, pkg/spacelift/*, tests/fixtures/**	Switches Spacelift stack-name config to template variant and updates error text and docs.
Config migration & deprecation notices pkg/config/config.go, pkg/utils/deprecation.go, pkg/config/load.go, cmd/docs.go	Adds handleDeprecatedSettings migration, new NotifyDeprecatedField helper, and adjusts env bindings (ATMOS_COLOR) and docs command to emit deprecation notices.
Errors centralization & usage errors/errors.go, internal/exec/utils.go, pkg/config/utils.go, internal/exec/aws_eks_update_kubeconfig.go	Adds new exported error constants and replaces inline error strings with standardized errors; updates messages to reflect new keys/env vars.
Internal code & tests updates internal/exec/*, internal/exec/aws_eks_update_kubeconfig.go, internal/exec/helmfile.go, internal/exec/utils.go, pkg/config/config_test.go, pkg/aws/*_test.go	Replaces literal messages/imports to use new errors/helpers and updated key names; tests adjusted to new NameTemplate references.
Examples, snapshots & fixtures website/static/examples/complete/atmos.yaml, website/static/examples/schemas/*.yaml, tests/snapshots/*.golden, tests/fixtures/**	Adds extensive example manifests for CLI/stack/vendor/workflow schemas; updates snapshots and many fixtures to reflect key renames.
Minor docs/help/text updates cmd/aws_eks_update_kubeconfig.go, demo/screengrabs/scripts/demo-stacks/start-your-project.sh, many website/docs/**	Help text, guide scripts, and numerous docs updated to reference the new template keys and wording edits.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant User
  participant CLI as Atmos CLI
  participant Loader as Config Loader
  participant Dep as DeprecationHandler
  participant Proc as Stack Processor
  User->>CLI: Run atmos command
  CLI->>Loader: InitCliConfig()
  Loader->>Dep: handleDeprecatedSettings(cfg)
  Note right of Dep: NotifyDeprecatedField used to log migrations
  Dep-->>Loader: mutated cfg (migrated fields)
  Loader-->>Proc: ProcessStacks(atmosConfig)
  alt missing name_template
    Proc-->>CLI: ErrMissingStackNameTemplate*
    CLI-->>User: error
  else success
    Proc-->>CLI: OK
    CLI-->>User: execute
  end

sequenceDiagram
  autonumber
  participant CI as GitHub Actions
  participant Repo as repository
  participant Check as checksum job
  participant Script as validate-all-schemas.sh
  participant YQ as yq/Python
  participant AJV as ajv
  CI->>Repo: checkout
  CI->>Check: compute MD5 of schema files
  alt checksums match
    Check-->>CI: success
  else mismatch
    Check-->>CI: fail and exit
  end
  CI->>Script: run schema validation
  Script->>YQ: convert YAML→JSON (per file)
  Script->>AJV: validate JSON against schemas
  AJV-->>Script: per-file results
  Script-->>CI: summary + exit code

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• cloudposse/atmos#1264 — Related rename/work on stacks.name_template vs name_pattern across code and docs.
• cloudposse/atmos#1123 — Related schema handling/registry and schema resource handling.
• cloudposse/atmos#1147 — Implements schema validation infra and validators, aligned with added schemas and validation script.

Suggested labels

no-release

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title succinctly captures the two main changes introduced by the pull request—extensive schema enhancements and a unified deprecation infrastructure—providing clear context without extraneous detail.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

• [ ] 📝 Generate docstrings

🧪 Generate unit tests (beta)

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment
• [ ] Commit unit tests in branch schema-page

---

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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[mergify[bot]]

💥 This pull request now has conflicts. Could you fix it @osterman? 🙏

[mergify[bot]]

💥 This pull request now has conflicts. Could you fix it @osterman? 🙏

[mergify[bot]]

💥 This pull request now has conflicts. Could you fix it @osterman? 🙏