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 follows the latest defaults, which can change behavior when Atmos is upgraded. 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 behavior are journaled. A new key that replaces implicit behavior, such as vendor.max_concurrency replacing sequential vendoring, is a default change. A feature introduced after your pinned date still works, with its initial defaults.
  • No pin means latest defaults. Projects without an edition pin adopt default changes when Atmos is upgraded. For example, from 2026-10-26, an atmos.yaml that omits template settings enables templates, Sprig, and Gomplate. Pin an earlier edition or explicitly disable these settings to retain their previous defaults.

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

Behavior Changes​

An edition can also select between old and new code behavior without introducing another configuration setting. Only changes explicitly recorded as behavior transitions and wired into the relevant command are covered; edition pins do not restore arbitrary historical behavior.

For example, the 2026-10-13 transition changes which attributes appear in plan-diff output. Earlier pins preserve the old display while current pins and unpinned projects use the new display. The transition date is inclusive, and partial dates use the same end-of-period rounding as default values.

Another example is the 2026-10-19 transition for step templates. Workflow, custom command, and lifecycle hook steps use the delimiters from templates.settings.delimiters from that date on; earlier pins keep {{ }} for steps.

From 2026-10-20, YAML functions require explicit tags: foo: !env "SOMETHING" reads the variable, while foo: "!env SOMETHING" remains literal text. Earlier pins retain legacy string-prefix evaluation. Unpinned projects use the new behavior; pin edition: "2026-10-19" while migrating. See the migration guide.

Both atmos list editions and atmos describe edition include these transitions. Their keys identify behaviors, not YAML settings, and their old/new values describe the two behaviors.

Example​

Browse the complete edition history for every journaled default and behavior change, including its date, previous value, new value, and source. The website and CLI read the same journal.

For example, a project pinned to September 2025 retains defaults and journaled behavior from that date unless explicitly overridden:

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​