Release boundaries
One source repository builds two independently selected release lines.
The release flow
context-circuit-source allows merge commits only, and its maintainer is the only person who merges. Contributors open pull requests into main.
mainis the trunk and never publishes. Work merges there. A pull request that changes something users see adds a change file under.changelog/; one that changes nothing users see writesNoneunder Release note instead.- Each minor line has a release branch,
release/X.Y, cut frommainat the minor's freeze. It publishes that minor and its patches. Cutting it publishes nothing. - A fix lands on
mainfirst, then reachesrelease/X.Ythrough a cherry-pick pull request that carries its change file. - A release-prep pull request into
release/X.YsetsVERSION,CLI_VERSION, or both, and adds each product's release request. - Merging it runs Publish on
release/X.Y: the CLI job first, then the template job. A version that is not on its own line's branch, such as2.6.0onrelease/2.5, or anything onmain, is refused. - After a stable release,
release/X.Ymerges back intomainfrom a topic branch cut from it, somaincarries the release's version files and requests and drops the change files it shipped.
A release candidate, such as 2.5.0-rc.1, follows steps 4 and 5 on the same branch and is published as a prerelease. A patch, such as 2.5.1, follows steps 3 to 6 on the existing release/X.Y.
Independent versions, ordered publication
VERSION selects the template release. CLI_VERSION selects the executable. Publish runs native validation, then CLI publication, then template publication. A product is published only when its version file names a release that is not out yet, so changing one line does not require releasing the other.
Compatibility
| Surface | Breaking | Not breaking |
|---|---|---|
| CLI | A removed or renamed command, flag, or JSON field; a changed exit code; a new refusal of something that used to work. | A new command, optional flag, or JSON field; clearer output text. |
| Template | A change that makes existing records invalid, or needs the workspace owner to act to keep working. | New skill text, a reworded instruction, a new optional file. |
| Workspace schema | Any change that needs a migration; the schema number goes up. | Documentation of existing fields. |
Schema 3 is the per-member ID layout. Moving a schema 2 workspace there is a migration, and one person on a team makes that split, commits it, and pushes it before anyone else changes anything. Separately, the pin guard refuses a writing change from a CLI that is not the pin and did not hand off, when it would move the workspace to schema 3 or when the two CLIs are on different release lines. A feature is deprecated in one minor release's upgrade notes before it is removed in a later release.
Variant forks
X.Y.Z-<label>.N is reserved for forks. A fork adds release/variant.env, the counter scripts/release-version.sh reads, and sets CC_VERSION_SUFFIX to its label: 1–20 lowercase letters, not a reserved label such as rc. The composed version is <base>-<label>.<counter>, built on a stable 2.Y.Z, and its CLI installs as <label>-context-circuit-cli. A public checkout prints VERSION and CLI_VERSION unchanged. A published stable tag is never published again.
Workspace and documentation updates
A template update applies the delta between the recorded tag and a later tag on the same release line, rather than copying a whole template over a project. Repository-owned landing files are read as evidence but not applied to a workspace, and neither is a delta that deletes the shared ID file or changes the schema version.
Maintain major-version guides for model changes and separate changelogs for each product's stable releases. Never infer release history from matching version numbers. Use available release evidence.