Documentation
¶
Overview ¶
Package edition implements date-anchored default resolution ("editions") for Atmos.
Atmos defaults change over time. Each change silently alters behavior for users when they upgrade. An edition is a date anchor — `edition: "2026"`, `"2026-07"`, or `"2026-07-16"` in atmos.yaml — that freezes defaults as they stood on that date.
The journal below is an append-only record of every change to a previously shipped default. Resolution is a rollback overlay: for a project anchored at date D, every journal entry dated after D applies its Old value instead of the current default. Entries dated on or before D, and keys with no post-anchor entries, keep their current defaults.
Brand-new defaults introduced by new features are never journal-gated — a newly introduced key supersedes nothing, so the feature loads with its initial default regardless of the anchor. Only changes to previously shipped defaults enter the journal.
The `edition` key itself is permanently exempt from journaling (enforced by journal_invariants_test.go); otherwise a pin could alter what pinning means.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrInvalidEdition = errors.New("invalid edition: expected YYYY, YYYY-MM, or YYYY-MM-DD")
ErrInvalidEdition is returned when an edition string is not a valid year, year-month, or year-month-day date.
var ErrUnknownBehavior = errors.New("unknown edition behavior")
ErrUnknownBehavior is returned when a behavior key has no behavior journal entry.
Functions ¶
func BehaviorChanged ¶
BehaviorChanged reports whether a named behavior transition applies at raw's edition pin. An empty pin selects the new behavior; a dated pin selects it on or after the journal entry's date, including end-of-period rounding. Each behavior key identifies exactly one transition, not a configuration key. Unknown keys and malformed pins return errors rather than silently selecting a code path. Callers pass the effective pin from AtmosConfiguration.Edition.
func Overrides ¶
Overrides returns the defaults a project anchored at `a` gets instead of the current ones: for each key whose default changed after the anchor date, the map holds the value from before the earliest post-anchor change. Keys with no post-anchor changes are absent — they keep their current defaults.
Types ¶
type Anchor ¶
type Anchor struct {
// Date is the fully resolved anchor date (UTC, midnight).
Date time.Time
// Raw is the string the user wrote, e.g. "2026-07".
Raw string
// Granularity records how much of the date the user specified.
Granularity Granularity
}
Anchor is a resolved edition pin.
Partial dates round to the END of the period they name — "2026" resolves to 2026-12-31 and "2026-07" to 2026-07-31 — so "the 2026 edition" includes every default change shipped during 2026, matching Rust's edition semantics.
func ParseAnchor ¶
ParseAnchor parses an edition string ("YYYY", "YYYY-MM", or "YYYY-MM-DD") into an Anchor, rounding partial dates to the end of the period they name.
type Change ¶
type Change struct {
// Key identifies the config default or behavior transition.
Key string `json:"key" yaml:"key"`
// Kind is the kind of the journal entries behind this change.
Kind Kind `json:"kind" yaml:"kind"`
// FromValue is the effective default at the `from` anchor.
FromValue any `json:"from_value" yaml:"from_value"`
// ToValue is the effective default at the `to` anchor.
ToValue any `json:"to_value" yaml:"to_value"`
// Entries are the journal entries between the two anchors that produced the change.
Entries []Entry `json:"entries" yaml:"entries"`
}
Change describes how a default or behavior differs between two anchors.
type Entry ¶
type Entry struct {
// Date is the day the change shipped, in "YYYY-MM-DD" form (typically the PR merge date).
Date string `json:"date" yaml:"date"`
// Key is a Viper config key for KindValue or a unique transition name for KindBehavior.
Key string `json:"key" yaml:"key"`
// Kind classifies the entry; only KindValue entries participate in default resolution today.
Kind Kind `json:"kind" yaml:"kind"`
// Old is the previous default value, or a description of the old behavior.
Old any `json:"old" yaml:"old"`
// New is the current default value, or a description of the new behavior. For
// the latest KindValue entry per key it must match setDefaultConfiguration.
New any `json:"new" yaml:"new"`
// Description explains the change in user-facing terms.
Description string `json:"description" yaml:"description"`
// Ref links to the PR or PRD that made the change.
Ref string `json:"ref" yaml:"ref"`
}
Entry records one change to a previously shipped default.
type Granularity ¶
type Granularity string
Granularity indicates how much of the date the user specified in an edition pin.
const ( // GranularityYear means the pin was "YYYY". GranularityYear Granularity = "year" // GranularityMonth means the pin was "YYYY-MM". GranularityMonth Granularity = "month" // GranularityDay means the pin was "YYYY-MM-DD". GranularityDay Granularity = "day" )
type Pin ¶
type Pin struct {
// Pinned reports whether an edition is set at all.
Pinned bool `json:"pinned" yaml:"pinned"`
// Edition is the raw pin as the user wrote it, e.g. "2026-07".
Edition string `json:"edition,omitempty" yaml:"edition,omitempty"`
// ResolvedDate is the fully resolved anchor date (partial dates round to the
// end of the period they name).
ResolvedDate string `json:"resolved_date,omitempty" yaml:"resolved_date,omitempty"`
// Granularity records how much of the date the user specified (year/month/day).
Granularity Granularity `json:"granularity,omitempty" yaml:"granularity,omitempty"`
// Source is where the pin came from: "flag", "env", or "config".
Source string `json:"source,omitempty" yaml:"source,omitempty"`
// Overrides lists each default or behavior the pin rolls back: FromValue is the pinned
// (effective) value, ToValue the latest default the project would get by unpinning.
Overrides []Change `json:"overrides" yaml:"overrides"`
}
Pin describes the effect of an edition pin for `atmos describe edition`.
func DescribePin ¶
DescribePin resolves a raw edition string into its full description. An empty raw string yields an unpinned description with no overrides. Source is caller-provided provenance ("flag", "env", or "config").
Source Files