From 46b18f300e5a7f65bcb9d37d65d9fcdd899aac94 Mon Sep 17 00:00:00 2001 From: Loris Leiva Date: Thu, 27 Aug 2026 15:47:29 +0100 Subject: [PATCH] Reconcile CONTRIBUTING with the mainless release model This PR updates the major-release playbook in CONTRIBUTING.md to defer branch, dist-tag and lifecycle mechanics to the ecosystem-wide [RELEASING.md](https://github.com/codama-idl/spec/blob/1.x/RELEASING.md) (cut / bake / promote, `release-N.x` dist-tags), documents the same-major invariant for the monorepo's public packages, and sweeps stale `main`/`vN`-branch references that predate the mainless model. --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3ca11afba..bfa80cab7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -22,15 +22,15 @@ Both pins are exact rather than ranges, so generated output only changes through ## Changesets -Any user-facing change needs a changeset: run `npx changeset add --empty` and edit the created file. One changeset file per concern; entries start with a verb. Never edit `CHANGELOG.md` files — they are generated by the release workflow. Note that the core packages (`codama`, `@codama/errors`, `@codama/node-types`, `@codama/nodes`, `@codama/validators` and the `@codama/visitors*` packages) version in lockstep as a fixed group, while the remaining packages version independently. +Any user-facing change needs a changeset: run `npx changeset add --empty` and edit the created file. One changeset file per concern; entries start with a verb. Never edit `CHANGELOG.md` files — they are generated by the release workflow. Note that the core packages (`codama`, `@codama/errors`, `@codama/node-types`, `@codama/nodes`, `@codama/validators` and the `@codama/visitors*` packages) version in lockstep as a fixed group, while the remaining packages version independently — below a shared ceiling: **all public packages carry the same major version** (the era, matching the branch name and the spec major it supports), so no package ever bumps its major on its own. Breaking changes to individual packages wait for the next major cut. ## Releasing a new major of the Codama standard -Releasing major N+1 of the [Codama spec](https://github.com/codama-idl/spec) requires the following steps in this repository. The design intent is that this list never grows: one new upgrade function per major, everything else mechanical. +Branch, dist-tag and lifecycle mechanics (cut / bake / promote) are defined once for the whole ecosystem in the spec repository's [RELEASING.md](https://github.com/codama-idl/spec/blob/HEAD/RELEASING.md). Releasing major N+1 of the [Codama spec](https://github.com/codama-idl/spec) additionally requires the following steps specific to this repository. The design intent is that this list never grows: one new upgrade function per major, everything else mechanical. 1. **Freeze the vN node types.** In `packages/spec-generators/package.json`, repoint the frozen alias at the final N.x spec release (renaming it `@codama/spec-vN`) and move the living `@codama/spec` pin to the (N+1).x release. Running `pnpm generate` then commits the frozen vN snapshot under `packages/upgrade/src/vN/` and restamps `CODAMA_VERSION` — remember to also freeze copies of the hand-written siblings (`brands.ts`, `Docs.ts`, `Version.ts`) next to the generated output, as done for v1. 2. **Write the upgrade step.** Add a single hand-written, pure `upgradeVNToVN+1` function to `@codama/upgrade` — a JSON-tree-in, JSON-tree-out converter in the `nodes-from-anchor` top-down style — and wire it into `upgrade()` as its `if (major <= N)` block. Export the vN types as a type-only namespace (`export type * as vN`) from the package index. -3. **Cut the vN maintenance branches.** The spec repository and the monorepos get a `vN` branch at their final N.x commit, publishing under the `vN` npm dist-tag via a branch-aware changesets workflow. Old majors receive clarifications and documentation fixes only, never semantic changes. +3. **Run the ecosystem lifecycle.** Cut this repository's `N.x` maintenance branch per RELEASING.md, after which `main` hosts the vN+1 work, with one codama-specific detail: the seeded major changeset covers **all** public packages, upholding the same-major invariant. `main` then versions as `(N+1).0.0-rc.n` under the `rc` dist-tag, bakes under `next`, and is promoted to `latest` while `N.x` switches to `release-N.x`. Old majors receive clarifications and documentation fixes only, never semantic changes. Two invariants protect consumers and must never be broken: