# 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`:

**File:** `atmos.yaml`

```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`](/cli/commands/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`](/cli/commands/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:

| Pin            | Resolves to  | Includes default changes through |
| -------------- | ------------ | -------------------------------- |
| `"2026"`       | `2026-12-31` | the end of 2026                  |
| `"2026-01"`    | `2026-01-31` | the end of January 2026          |
| `"2026-01-15"` | `2026-01-15` | January 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](/cli/commands/terraform/plan-diff#edition-compatibility). 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`](/templates#configure-templating)
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](/changelog/explicit-yaml-function-tags).

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](/cli/editions) 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:

**File:** `atmos.yaml`

```yaml
edition: "2025-09"
```

Pin a single invocation instead with the global flag:

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

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

```shell
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](/cli/configuration/settings/experimental) 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

- [`atmos list editions`](/cli/commands/list/editions) — Browse the journal of default changes, or diff two editions
- [`atmos describe edition`](/cli/commands/describe/edition) — Show the active pin and every default it rolls back
- [Experimental Features](/cli/configuration/settings/experimental) — Control how Atmos handles experimental features
- [CLI Configuration](/cli/configuration) — Overview of CLI configuration