v2 transition tracking

[lorisleiva]

Tracking issue for the Codama IDL v2 major transition, following RELEASING.md.

Status: 🔵 Candidacy — release candidates shipping, no candidate declared yet.

Event	Date
Cut	2026-08-27
First rc	–
Candidate declared	–
Promote	–

v2 scope

Ten design issues, in three tiers. Tier A is settled design; Tier B is committed direction with open design points; Tier C has an explicit go/no-go before the candidate is declared and slips to v3 without blocking. Ticked when the change lands in src/v2/.

Scope checklist

Tier A — settled

• [v2] Add spec-level base attributes and give every node a plugins list #124 Spec-level base attributes; plugins on every node
• [v2] Replace nested type wrappers with a flat transforms array #125 Flat transforms array replacing nested type wrappers
• [v2] Allow any type node as account data #126 Any type node as account data
• [v2] Unify enum variants into a single enumVariantTypeNode #127 Single enumVariantTypeNode
• [v2] Remove the origin attribute from programNode #128 Remove programNode.origin

Tier B — committed, design open

• [v2] Rename name to identifier and drop the casing mandate #129 name → identifier; no casing mandate
• [v2] Introduce path expressions as a shared reference DSL #130 Path expressions as a shared reference DSL
• [v2] Replace instruction arguments with a single data type node #131 Instruction data type node; remove extraArguments and resolvers
• [v2] Rework the numeric system for lossless, format-aware numbers #132 Numeric system rework (types and values)

Tier C — go/no-go gate

• [v2] Introduce textNode for all human-facing text #133 textNode for all human-facing text

Candidate declaration

Declared on the announcement thread (body edit + comment). Not declared yet.

Release train

• codama: freeze v1 node types, add upgradeV1ToV2, living spec pin → rc
• codama-rs: promote the workspace to 1.0.0 on main (freeze the v1-era API), then cut the 1.x maintenance branch and mirror the codama steps in Rust
• renderers + CLI: cut their own majors to consume the new codama major

Phase checklists

Cut (docs)

• 1.x maintenance branch cut; main hosts the v2 work in pre-release mode (Cut the 2.x branch #105, Restore main as the bleeding-edge branch #107)
• Tracking issue opened

Candidacy (docs)

• Declare the candidate set + earliest promote date on the thread
• Announcement thread opened: Codama v2 is in development — follow this thread #121 (pin it manually)
• Freeze: fixes only until promote

Promote (docs)

• Dispatch promote (commits --tag release-1.x on 1.x, pre exit on main, flips default branch)
• Merge the release PR — 2.0.0 publishes and takes latest
• Audit git log --oneline main..1.x for unported commits (superset guarantee)
• Closing announcement; close this issue

Ecosystem adoption checklist

Integrators (explorers, wallets, indexers, program repos) and their validation status against the candidate. Gates the promote. To be filled during candidacy.