Skip to main content

Edition

Pin your project to an Atmos edition — a date anchor for defaults — so upgrading Atmos never silently changes behavior. Every change to a previously shipped default is journaled with the date it changed; a pinned project keeps the defaults as they stood on the pinned date.

Experimental

Configuration​

The edition pin is a top-level key in atmos.yaml:

atmos.yaml
# Pin defaults to a date anchor: "YYYY", "YYYY-MM", or "YYYY-MM-DD"
# Can also be set using the 'ATMOS_EDITION' ENV var, or the '--edition' global flag
edition: "2026-01"
edition

A date anchor for defaults, written as "YYYY", "YYYY-MM", or "YYYY-MM-DD" (quote it — a bare 2026-01 is a YAML date, not a string). Defaults that changed after the anchor keep their pre-change values; everything else follows the latest defaults. When unset, the project always follows the latest defaults — nothing changes for existing projects. Can also be set using the ATMOS_EDITION environment variable or the --edition global flag.

Precedence​

When the edition is set in more than one place, the effective value is resolved in this order (highest wins):

  1. --edition global flag
  2. ATMOS_EDITION environment variable
  3. edition in atmos.yaml

Run atmos describe edition to see the effective pin and where it came from (flag, env, or config).

How Editions Work​

Atmos defaults change over time. Before editions, each change silently altered behavior for every project the moment it upgraded. Now, every change to a previously shipped default is recorded in a journal with the date it changed, the old and new values, and the pull request that changed it. Browse the journal with atmos list editions.

A pinned project resolves defaults as a rollback overlay:

  • Defaults that changed after the pinned date keep their pre-change values. For example, the built-in pager default changed from on to off on 2025-10-16, so a project pinned to edition: "2025-09" keeps the pager on.
  • Explicit configuration always wins. A value you set in atmos.yaml (or via environment variables or flags) beats the pin, exactly as it beats the latest defaults.
  • New features are unaffected. Only changes to previously shipped defaults are journaled — never new keys. A feature introduced after your pinned date still works, with its initial defaults.
  • No pin means latest defaults. Projects without an edition key behave exactly as before.

End-of-Period Rounding​

Partial dates round to the end of the period they name — "the 2026 edition" includes every default change shipped during 2026, matching Rust's edition semantics:

PinResolves toIncludes default changes through
"2026"2026-12-31the end of 2026
"2026-01"2026-01-31the end of January 2026
"2026-01-15"2026-01-15January 15, 2026

Example​

The journal currently records ten default changes, reaching back to February 2025:

DateKeyOldNewDescription
2025-02-11logs.file/dev/stdout/dev/stderrLogs are written to stderr so they never contaminate pipeable command output on stdout
2025-09-23logs.levelInfoWarningInformational log messages are hidden unless requested
2025-10-16settings.terminal.pagertruefalseThe built-in pager is disabled by default; long output prints directly to the terminal
2025-12-06stacks.inherit.metadatafalsetrueComponent metadata is inherited from base components like vars and settings
2026-02-10components.helmfile.use_ekstruefalseHelmfile EKS integration is opt-in; kubeconfig is no longer downloaded automatically
2026-07-06settings.terminal.help.filterfalsetrueBare --help shows a focused view without the GLOBAL FLAGS section; --help=all prints everything
2026-07-13describe.error_modestrictwarnDescribe commands substitute (computed) for unresolved YAML function values and continue
2026-07-13list.error_modestrictwarnList commands substitute (computed) for unresolved YAML function values and continue
2026-07-17describe.component.filterfullschemaComponent descriptions show only the sections a stack manifest can define
2026-07-16describe.provenancefalsetrueComponent descriptions include provenance annotations (which stack file set each value)

A project pinned to September 2025 predates eight of these changes (everything from the pager change onward), so it keeps the pager enabled, the Helmfile EKS integration on, metadata inheritance off, unfiltered help, strict error modes, the full component-description filter, and provenance off:

atmos.yaml
edition: "2025-09"

Pin a single invocation instead with the global flag:

atmos --edition=2025-09 helmfile apply demo --stack=dev

Preview what changes if you unpin (or upgrade your pin):

atmos list editions --from=2025-09

Experimental Status​

Editions are an experimental feature. With the default settings.experimental: warn, a pinned project prints an experimental notice; settings.experimental: disable blocks the feature entirely. See Experimental Features for the available modes.

Environment Variables​

ATMOS_EDITION
Edition pin (YYYY, YYYY-MM, or YYYY-MM-DD). Overrides edition in atmos.yaml; overridden by the --edition flag.

See Also​