Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

RFD-0012 — Package manifest is unified; editions are parse-time only

Committed Opened 2026-05-03 · Committed 2026-05-03

Question

Argon packages come in several flavors: leaf libraries, runnable projects, multi-package workspaces. Should each flavor get its own manifest schema, or one unified schema with optional sections? And how does the language handle source-syntax evolution across releases?

Decision

Unified manifest schema at ox.toml. Library, project, and workspace flavors use the same top-level schema with different sections populated. A library has [package] only; a project adds [bin] or runtime sections; a workspace has [workspace] listing members. The schema is one document; the flavor is determined by which sections are present.

Editions are integer-numbered, opt-in per package, parse-time only. A package’s edition = 2026 field selects a parser dialect. Semantics are stable across editions — only syntactic surface evolves. The compiler’s IR shape, type system, and runtime semantics are edition-independent.

Rationale

One manifest schema removes a class of “which schema is this” questions. Tooling that processes manifests (resolver, registry uploader, diff tools) walks one structure. Authors learn one schema. The flavor distinction is a presence-check, not a parser fork.

Editions confined to parse-time. The motivation for editions is “we want to change the syntax without breaking existing code.” That’s a parser concern. Letting editions affect IR or runtime semantics introduces a combinatorial space (which IR for which edition?) that compounds with every release. Confining the difference to parse-time means the rest of the compiler operates on a single canonical IR regardless of source edition.

Integer numbering, not date-based. Editions don’t ship at predictable cadences. edition = 2026 at year boundaries would imply something the cadence doesn’t match. Sequential integers (edition = 1, edition = 2) decouple the edition number from the calendar.

Consequences

  • Manifest parser admits all top-level sections; the flavor check happens after parsing.
  • The compiler’s parser dispatches on the package’s edition field; downstream phases see one canonical AST.
  • Edition migration is a syntactic transformation, never a semantic one. A migration tool can rewrite source from edition N to edition N+1 without changing meaning.
  • Workspace members’ editions are independent; one workspace can host packages on different editions.