Pantheon Release Process¶
🇧🇷 Versão em Português disponível: Leia em Português
How versioning, releases, branching strategy, and packaging work.
Branching & Release Buffering Strategy (Trunk-Based Delivery)¶
Pantheon adopts a Trunk-Based Delivery with Release Buffering workflow. All development occurs on short-lived feature branches, lands on main via reviewed Pull Requests, buffers new capabilities in the [Unreleased] changelog section, and releases to npm/GitHub exclusively when a maintainer explicitly decides to cut a release:
flowchart TD
subgraph FeatureBranches["🛠️ Short-Lived Feature Branches"]
B1["feat/cookbook-expansion"]
B2["feat/new-mcp-enhancement"]
B3["fix/session-cleanup"]
end
subgraph PullRequests["📋 Pull Requests & CI Verification"]
PR1["PR #432"]
PR2["PR #433"]
PR3["PR #434"]
end
B1 --> PR1
B2 --> PR2
B3 --> PR3
PR1 & PR2 & PR3 -->|"10/10 CI Checks PASS"| Main["🌿 main (Stable Trunk)"]
subgraph Buffer["📦 Release Buffer"]
Main -->|"Automated Accumulation"| Unreleased["CHANGELOG.md [Unreleased]"]
end
subgraph ReleaseGate["🔒 Explicit Release Cut Gate"]
Unreleased -->|"Human Maintainer Decision: CUT"| Script["node scripts/versioning.mjs apply minor"]
Script --> Tag["Git Tag: vX.Y.Z"]
Tag --> Publish["🚀 Release Workflow (npm + GitHub Release)"]
end
Core Principles:¶
mainis Always Tested & Deployable: Code inmainis never broken. Every merge must pass all 10 CI checks (validate,test-suite,plugin-ts-coverage,security-scan,commitlint,CodeQL, etc.).- Merges Do NOT Trigger Package Releases: Merging a PR into
mainautomatically triggers documentation updates on GitHub Pages (latest), but never publishes to npm or creates release tags. - Buffering in
[Unreleased]: Completed features accumulate in the## [Unreleased]section ofCHANGELOG.mduntil the maintainer decides the milestone is complete. - Explicit Release Cutting: A release is only triggered when the maintainer runs the release script (
node scripts/versioning.mjs apply [patch|minor|major]), which promotes[Unreleased]to the new version header, synchronizes manifests, and creates the release tag.
Versioning Policy¶
Pantheon follows Semantic Versioning based on Conventional Commits:
| Commit pattern | Version bump |
|---|---|
BREAKING CHANGE or type!: in scope |
MAJOR (x.0.0) |
feat: |
MINOR (x.y.0) |
fix:, chore:, docs:, refactor:, etc. |
PATCH (x.y.z) |
Candidate version: the manifests in this checkout express the version being
prepared; they do not confirm a publication. A beta is published only after
the Release workflow completes successfully. To check which version is
actually published, consult the npm beta dist-tag.
Version Commands¶
# Show current version, latest stable git tag, and pending release status
node scripts/versioning.mjs status
# Sync all manifests + promote [Unreleased] → [vX.Y.Z] (recommended bump)
node scripts/versioning.mjs apply # type auto (from commits)
node scripts/versioning.mjs apply minor # explicit type: patch | minor | major
node scripts/versioning.mjs apply --notes # pre-fill the promoted entry with
# release notes generated from commits
# Advance the committed beta line and promote the manual [Unreleased] body
node scripts/versioning.mjs apply --beta
node scripts/versioning.mjs beta # alias for apply --beta
# Replace [Unreleased] with generated notes since the latest beta tag
node scripts/versioning.mjs apply --beta --notes
# Merge pending notes into an already-promoted candidate without a version bump
node scripts/versioning.mjs changelog 1.6.0-beta.10
# Generate release notes from conventional commits (lastTag..HEAD)
node scripts/release-notes.mjs # stable vX.Y.Z tags only
node scripts/release-notes.mjs --draft # last 30 commits, no tag lookup
# CI-side consistency check (run in the `validate` job of ci.yml)
node scripts/version-check.mjs
# Dry-run of the release payload (status + release notes + pack)
npm run release:dry-run
After a beta version bump, typecheck and rebuild the TUI workspace from the repository root. The dist bundles embed the package version, and CI checks their freshness; do not install dependencies with a nested prefix.
npm run typecheck --workspace=src/plugins/tui
npm run build --workspace=src/plugins/tui
apply syncs the version manifests (package.json, plugin.json,
pyproject.toml, src/plugins/tui/package.json) and promotes the
[Unreleased] changelog section to a versioned entry. apply --beta (alias
beta) syncs the manifests to the next committed X.Y.Z-beta.N and
promotes [Unreleased] to ## [vX.Y.Z-beta.N]; without --notes, it keeps
the manual [Unreleased] body. With --beta --notes, the promoted body is
generated from commits since the latest beta tag (not the latest stable tag),
using the same release-notes parser and renderer as the stable path. It fails
before writing files if no beta baseline exists or the generated notes are
empty. Do not edit CHANGELOG.md by hand. When the target version section
already exists, versioning.mjs changelog <version> merges [Unreleased]
into that section and resets the template without advancing the package
version or duplicating the release heading. Release validation also
keeps the root pair (package.json + package-lock.json) and the TUI pair
(src/plugins/tui/package.json + src/plugins/tui/package-lock.json) in the
same versioned inventory. The TUI is a root workspace, so CI installs both
with a single npm ci --ignore-scripts at the root; the nested TUI lock is
still versioned and still shipped because the user-facing postinstall syncs
against it. It no longer creates git tags — tags are
workflow-owned (see below).
Version Bump (the only manual step)¶
- Create a branch off
main. - Bump the version:
or edit
node scripts/versioning.mjs apply minor # or patch/majorpackage.jsondirectly — the version is the release signal. The TUI manifest (src/plugins/tui/package.json) carries the same version;npm run version:checkfails when the two drift.node_modules/state is irrelevant here: the TUI is a root workspace, so one rootnpm ci --ignore-scriptsinstalls it. - Fill in the promoted changelog section with the release notes for the upcoming version. The release body is extracted from this section, so it must exist and be accurate.
- Commit + push + open a PR to
main. Review the complete working-tree diff, then stage every intentional release change: all outputs produced byversioning.mjsand any release docs deliberately edited. The paths below are illustrative and incomplete; check the full diff rather than treating this list as exhaustive. In particular, do not omitsrc/plugins/tui/dist/tui.js: the bundle embeds the package version and CI checks TUI dist freshness. Leave unrelated changes and untracked RED tests out of the release commit.
git status --short
git diff
git add CHANGELOG.md docs/RELEASING.md package.json package-lock.json \
plugin.json pyproject.toml src/plugins/tui/package.json \
src/plugins/tui/package-lock.json src/plugins/tui/dist/tui.js
# Add any other intentional paths found while reviewing the complete diff.
git diff --cached --check
git diff --cached --name-only
git diff --cached
git commit -m "chore(release): vX.Y.Z"
git push -u origin <branch>
- Wait for CI. The PR must pass
validate(version manifests, engine, packaging, sandbox),test-suite,plugin-v2-ts-coverage,commitlint,security-scan, andCodeQLbefore merging.ci.ymlalso runs on pushes tomain, so the merged SHA carries its own CI evidence.
No tag is created locally. Merging an ordinary PR does not release. To publish a stable version, use the explicit
Releaseworkflow dispatch after the intended commit is onmain; it validates manifests and preserves the exact target-SHA/idempotency checks.
Release Notes¶
Release notes live in the version's CHANGELOG.md section and that section —
verbatim — is the GitHub Release body. The canonical format is the hybrid:
curated ### 🆕 What's New highlights on top, Keep a Changelog subsections
below, in fixed order, in English:
### 🆕 What's New ← curated highlights (≤6 bullets, ≤140 chars each)
### Added ┐
### Changed │ Keep a Changelog — omit empty sections, keep this order
### Deprecated │
### Removed │
### Fixed │
### Security ┘
### ⚠️ Known Issues ← optional, last
### ✅ Closed Issues ← optional, last
Rules enforced by the tooling (see "Enforcement" below):
- Only the headings above, in this relative order, no duplicates, no
##or####inside the section. - Bullets open with a bold lead:
- **<scope>** — <text>(breaking: a💥prefix before the bold lead). Unscoped bullets may use- **<subject>**. ### 🆕 What's Newis authored by hand (it is never generated): at most 6 bullets, one terminal line each (≤140 chars — the TUI window contract).- No
TODO/TBD/FIXME/XXXplaceholders, no empty subsections, no bullet over 200 chars (continuation lines included).
Type → section mapping¶
node scripts/release-notes.mjs (and versioning.mjs apply --notes) generate
the KaC sections from conventional commits — never written from scratch.
Commitlint (12 types / 40 scopes) validates every commit before it merges, so
the generator can always group the history:
| Commit type | Generated section |
|---|---|
feat |
### Added |
perf, docs |
### Changed |
fix |
### Fixed |
security |
### Security |
--known-issues "text" (CLI flag, repeatable) |
### ⚠️ Known Issues (omitted when the flag is absent — never emitted empty) |
Closes #N / Fixes #N / Resolves #N in the commit body |
### ✅ Closed Issues — bullet - #N - <subject> (deduped; omitted when no refs exist) |
release scope (maintainer-only, any commit type) |
omitted from all public notes, including Closed Issues references |
chore, refactor, test, ci, build, style, revert (and unknown types) |
omitted — internal, never user-facing |
BREAKING CHANGE footer or type!: / type(scope)!: |
💥 prefix on the bullet inside its section (e.g. - 💥 **scope** — subject) — no dedicated Breaking section |
### 🆕 What's New is NOT generated — curate it by hand on top of the
generated sections. Deprecated and Removed have no commit type; author
them by hand when the release needs them.
The release scope is reserved for maintainers' internal release tooling.
Commits using it are excluded before both section grouping and issue-reference
collection, so they cannot appear in any section.
Merge commits ("Merge …") and empty-subject chores are skipped.
Generate the notes¶
# Commits since the latest stable tag (strict vX.Y.Z, pre-releases excluded)
node scripts/release-notes.mjs
# Same output without reading git tags (last 30 commits) — quick preview or
# pre-first-tag use
node scripts/release-notes.mjs --draft
# Add a manual Known Issues entry (repeatable; omitted from output when absent)
node scripts/release-notes.mjs --known-issues "widget API is unstable"
# Pre-merge review: version status + generated notes + pack dry-run
npm run release:dry-run
The script exits 0 whenever it can generate. stdout is markdown ready to
paste into the [Unreleased] CHANGELOG section (diagnostics go to stderr).
Release body by channel¶
release.yml extracts the release body from the committed CHANGELOG.md for
both dispatch channels; only the stable channel attaches it to a GitHub Release:
| Channel | Notes source |
|---|---|
| stable | node scripts/changelog-extract.mjs X.Y.Z reads the curated ## [X.Y.Z] section from CHANGELOG.md; the dispatch fails if the section is missing. Used as the GitHub Release body. |
| beta | node scripts/changelog-extract.mjs X.Y.Z-beta.N reads the curated ## [X.Y.Z-beta.N] section from CHANGELOG.md; the dispatch fails if the section is missing. Carried in the release artifact only — beta creates no GitHub Release. The workflow does not regenerate notes at dispatch time. |
| recovery | node scripts/changelog-extract.mjs v<recovery_version> reads the section from the CHANGELOG at the recovery target SHA, so a republished release keeps the canonical body. The static note (Recovery publish for existing tag ...) is the last resort for tags predating the CHANGELOG section. |
Enforcement (the release body can never drift again)¶
- Author time — CI runs
npm run docs:check-changelog, which validates the[Unreleased]and newest-stable sections against the canonical format (scripts/changelog-format.mjs) on every PR. - Release time — release gate (e) validates the exact committed section before anything is tagged; a format violation fails the dispatch.
- After publication — the title is always
Pantheon <tag>(workflow-set), and a re-run of the release workflow for a version whose GitHub Release already exists compares the published body with the canonical section and fails on divergence with the remedy (gh release edit <tag> --notes-file release-artifact/release-notes.md). Hand-editing a published body is not part of the process; a correction goes into the CHANGELOG and a recovery dispatch republishes it.
The version is committed, so a CHANGELOG.md section is authorable before the
dispatch and is required for both channels. Stable apply --notes uses
the latest stable tag; beta note generation is opt-in through
apply --beta --notes and uses the latest beta tag. Without --notes, beta
notes remain manually curated. In either channel, the dispatch extracts the
committed changelog section and does not generate notes itself.
Flow¶
- Commit — Conventional Commits enforced by commitlint (local hook + CI).
- Generate — For stable,
node scripts/release-notes.mjsuses the latest stable tag; paste its output into[Unreleased]or useapply --notes. For beta, useapply --beta --notesto generate since the latest beta tag, or leave--notesoff to keep manually curated content. - CHANGELOG —
node scripts/versioning.mjs apply minor [--notes]bumps the stable manifests and promotes[Unreleased]→[vX.Y.Z]; beta usesapply --beta [--notes]and promotes to[vX.Y.Z-beta.N]. With--notesthe promoted entry is pre-filled from grouped commits (the canonical### Added / Changed / Fixed / Security / ⚠️ Known Issues / ✅ Closed Issuessections); it replaces any manual[Unreleased]content — add the curated### 🆕 What's Newblock (and Deprecated/Removed when needed) after generating. Beta--notesfails before writes when there is no beta baseline or the generated notes are empty. Review the diff before committing. - Release body by channel —
node scripts/changelog-extract.mjs <version>pulls the curated versioned section into the GitHub Release body for both stable (X.Y.Z) and beta (X.Y.Z-beta.N), and fails if the section is missing; recovery extracts the section at the recovery target (the static note is the last resort for tags predating the section). - Publish — the workflow tags the exact dispatch target SHA and publishes
to npm (stable or beta per the
release_channelinput).
Stable Release (manual dispatch)¶
Dispatching .github/workflows/release.yml
without recovery inputs runs the stable release path:
- Type: channel=
stable, npm dist-tag=latest. - Version gate — package.json must be a clean
X.Y.Zand not strictly behind the latest stable git tag (exactvX.Y.Ztags only;-beta.*pre-release tags are excluded from the comparison). Fails loudly if the version was never bumped. - Pack and verify — the validation job packs exactly one immutable npm
tarball with lifecycle scripts disabled. It records that tarball's
SHA-256 together with the full
TARGET_SHA; the release job recomputes the digest and rejects any mismatch. - Idempotent guard — if tag
vX.Y.Zexists AND its GitHub Release exists, exit 0 (already released). If the tag exists but the release is missing, continue and complete the release (tag creation is skipped). - Release body —
node scripts/changelog-extract.mjs X.Y.Zextracts the## [X.Y.Z] - datesection fromCHANGELOG.mdinto the runner temp path$RUNNER_TEMP/release-notes.md(published asrelease-artifact/release-notes.md); fails if the section is missing. - Tag creation (workflow-owned) — a tag ref is created through the repository-scoped GitHub API on the exact dispatch target SHA.
- GitHub Release —
gh release create vX.Y.Z --target <dispatch-sha> --verify-tag --title "Pantheon vX.Y.Z" --notes-file release-artifact/release-notes.md. - npm publish (final step) — gated by the idempotency
lookup, then that same tarball (without repacking) is published with
--tag latest --access public --provenance. The SHA-256 validated in the validation job is therefore the SHA-256 of the file published to npm.
A global concurrency group (release, no cancel-in-progress) serializes
runs so beta and stable paths can never double-publish.
Package and evidence contract¶
The release evidence is fail-closed and has one artifact identity:
- root dependencies and the TUI workspace use one
npm ci --ignore-scriptswithpackage.jsonandpackage-lock.json; - the TUI manifest and lockfile remain independently validated as package and publish evidence;
- a release creates one npm
.tgztarball, computes one SHA-256, and carries that exact file and digest from validation to publication; a secondnpm packis not a valid replacement; - the tarball and GitHub tag/release are bound to the same full
TARGET_SHA.
Any npm ci failure blocks the run. There is no npm install fallback, and
PANTHEON_ALLOW_NPM_INSTALL_FALLBACK is not part of the current contract.
Six release gates¶
The validate job of release.yml runs six gates on the frozen TARGET_SHA.
Each prints GATE <name>: PASS and writes a named evidence file to
$RUNNER_TEMP/gate-evidence/<name>.json; the directory is uploaded as
release-gate-evidence-<run_id> (90-day retention). There is no fallback: a
command that cannot run, a missing artifact, an unsupported host, or a SKIP
is a failed gate, and a failed gate aborts before the artifact upload and
before any release credential is exposed.
| Gate | Executed by | Fails when | Evidence |
|---|---|---|---|
| (a) tests | scripts/release-gates.mjs tests: pytest + src/mcp coverage ≥ 80, test:node, test:ts, coverage:plugin-v2, test:install; pytest runs in an isolated venv built from src/mcp/requirements-mcp.txt |
any suite, coverage threshold, or the mandatory install tier fails; an unsatisfiable or unverified pin set fails the gate | tests.json |
| (b) host compatibility | scripts/release-gates.mjs host: each measured host installed and exercised in an isolated sandbox; the gate reports a supported family with no row as "supported, unmeasured" instead of failing it |
a measured row fails, or a known-broken host is listed | host.json |
| (c) install | scripts/release-gates.mjs install: the immutable .tgz installed globally, headless init, validate-sandbox-install.mjs, and a host-backed tool canary on OpenCode 2.0.30 |
install, init, source comparison, MCP/doctor checks, or canary fails or skips | install.json, install-canary.log |
| (d) package | scripts/release-gates.mjs package: SHA-256 recomputed over the same .tgz, payload inspected, package:validate |
the digest, name, version, target SHA, or payload disagree; no second npm pack is accepted |
package.json |
| (e) changelog | scripts/release-gates.mjs changelog: changelog-extract.mjs |
the [version] section is missing or empty; recovery checks the tag instead |
changelog.json, changelog.md |
| (f) metadata | scripts/release-gates.mjs metadata: version-check.mjs + validate-node-engine-policy.mjs |
manifests drift, the channel/version shape is wrong, or the SHA is not 40 hex | metadata.json |
The install canary configures the installed package's src/plugin-v2 directory
using the installer's object-form plugins entry, so imports resolve against the
installed package's runtime dependencies rather than a checkout shim. A
preflight turn fails the canary before catalog assertions if the installed plugin
does not register hashline_edit with its output descriptor. The canary then
checks the Code Mode catalog, a rejected hashline reference (no write), and one
valid edit limited to a temporary project file. It mocks only the model endpoint
with a local scripted SSE server. This proves behavior for the installed artifact
on the gate's OpenCode 2.0.30 host; it does not prove npm publication, the GitHub
Release workflow, or compatibility with host versions not run by that gate.
The host evidence matrix is declared in release.yml (PANTHEON_RELEASE_MATRIX)
and is validated by the gate, not trusted. Support is family-level: the gate
requires no row per family, reports a family with no row as "supported,
unmeasured", and fails only when a measured row fails or a known-broken host is
listed. See Compatibility for the support policy and the
known-broken set. A measured row that cannot run is a failure — the release path
has no SKIP. The automatic release matrix exercises four OpenCode 2.x hosts;
it no longer proves compatibility with OpenCode 1.19.x. 1.7.0 is the last
version supporting the OpenCode V1 contract (owner decision, 2026-11-07): the
1.19.x support declaration holds through the 1.7 line and is retired in the
next minor. This is a limit of automatic release validation, not a change to
the support policy.
Python test environment (gate a)¶
The Python suite imports fastmcp/mcp at collection time, so its verdict only
means something against the pins in src/mcp/requirements-mcp.txt. Gate (a)
therefore does not use the runner's ambient interpreter:
- the
validatejob creates$RUNNER_TEMP/gate-venvwithpython3 -m venvfrom the interpreter pinned byactions/setup-python(python-version: '3.12', i.e. CPython 3.12.x onubuntu-latest; the package metadata declaresrequires-python >= 3.11), installscoverage pytest pyyaml,pytest-asyncio==1.3.0, and-r src/mcp/requirements-mcp.txt -r src/mcp/requirements-vision.txt; PANTHEON_PYTHONis exported to that venv andrelease-gates.mjsresolves every Python command through it. A set-but-missing or non-executablePANTHEON_PYTHONis a hard failure, never a fallback to the ambientpython3;pip checkand an explicit assertion that every==pin in both requirements files is installed at exactly that version run before pytest. A failed venv creation, download, install, or pin assertion aborts the job (fail-closed viaset -euo pipefail); no failure is downgraded to a skip;actions/setup-python'scache: pipstill applies: the venv's pip shares~/.cache/pip, so the download cache is reused while the install itself stays isolated;- the CI
test-suitejob builds the same venv ($RUNNER_TEMP/ci-venv) and pointsPANTHEON_PYTHONat it, so CI and the release gate share one environment contract; tests.jsonrecords the interpreter path andpython --versionused for the run.
Local equivalent of the gate's Python step:
python3 -m venv /tmp/pantheon-gate-venv
/tmp/pantheon-gate-venv/bin/python -m pip install -r src/mcp/requirements-mcp.txt -r src/mcp/requirements-vision.txt
PANTHEON_PYTHON=/tmp/pantheon-gate-venv/bin/python \
node scripts/release-gates.mjs tests --evidence-dir /tmp/gate-evidence
Running pytest on an interpreter without these pins is not evidence: with
fastmcp 3.4.2 / mcp 1.28.0 on PATH, tests/test_persistence_goals.py
fails at collection by design, which is an environment defect, not a
product defect.
Test tiers¶
- Default (developer loop):
npm run test:noderunstests/*.mjsandtests/pantheon/*.mjsexcludingtests/install-opencode.test.mjsandtests/install-e2e.test.mjs. A barenode --testover those files skips their cases with an explicit reason unless the tier is opted into. - Heavy tier (optional locally, mandatory in release):
npm run test:installsetsPANTHEON_RUN_INSTALL_TESTS=1and runs both real-install files.npm test/test:alldoes not include it, so the local loop stays fast; gate (a) always includes it.
Coverage contract¶
- Required: Python
src/mcpbranch coverage ≥ 80% (coverage report --fail-under=80) and thesrc/plugin-v2.tsline measurement (npm run coverage:plugin-v2). Both run in gate (a). - Not PASS: Node coverage (
npm run coverage) is report-only and enforces no threshold; TypeScript undersrc/outside the plugin-v2 measurement is unmeasured. Neither may be cited as evidence that a threshold passed. - No new threshold is introduced by this contract.
Memory MCP packaging¶
src/mcp/memory_mcp.py is the canonical Memory MCP server. The
scripts/memory_mcp.py source-tree entrypoint delegates to it, and the runtime
installer copies the canonical source into the installed scripts directory.
tests/test_mcp_scripts_sync.py checks that the compatibility entrypoint exposes
the same tool list as the canonical server.
Where a release may be cut (branch hygiene, 2026-11-05)¶
Releases are cut only from the release line (release/<X.Y.Z>):
- Work happens on a feature branch — or in a task worktree at
<project-parent>/.pantheon-worktrees/<repo>/<task>(AGENTS.md convention). A feature branch/worktree NEVER bumps versions, NEVER edits the CHANGELOG's promoted sections, and NEVER runsnpm publish— the tarball must be the artifact of the release line's tip. - Landing: PR into
release/<X.Y.Z>; merge. The version bump (apply --beta) and the curated## [X.Y.Z-beta.N]CHANGELOG section are committed on the release line (as thechore(release): ...commit), then therelease.ymldispatch runs the sanctioned publish. - Manual
npm publishis a recovery exception only: when it has to happen outside the workflow (e.g. the workflow's publish path was bypassed), the very next step is therelease.ymlrecovery dispatch (or, minimally, the immutablevX.Y.Z-beta.Ntag on the release SHA) so the published artifact is always tag-backed. - Worktrees are task-scoped and removed when the task lands; stale task worktrees from finished work are deleted (branches: delete when fully merged; keep unmerged refs for review).
The 🆕 What's New summary (window contract)¶
Every promoted release section opens with a ### 🆕 What's New block as its
FIRST subsection: at most 6 bullets, one terminal line each (≤140 chars,
bold lead) — the one-time TUI window shows ONLY this block, paginated, and
points at CHANGELOG.md for the rest. Long prose belongs under
### Added / Changed / Fixed (read by humans on GitHub/npm), never in the
window block. The ## heading level is rejected by the format validator
(scripts/changelog-format.mjs) in maintained sections: ### keeps the
block inside the extractor's boundaries.
Beta Releases (explicit dispatch with release_channel=beta)¶
Publication is authorized only by an explicit workflow_dispatch of
release.yml. PR labels, pushes, merges, and tags never trigger or authorize a
release. Dispatching with release_channel=beta runs the beta path; a beta
recovery is triggered by a dispatch carrying recovery_version plus
recovery_target_sha (and recovery_pr_number only for the legacy format); a
dispatch without recovery inputs and release_channel=stable (the default) is
the stable path.
- Type: channel=
beta, npm dist-tag=beta. - Committed version —
apply --betaadvancedpackage.json(and the other manifests) toX.Y.Z-beta.Nbefore the dispatch. The workflow reads the committed version; it never computes a beta version and never queries npm for a baseline. A version that is notX.Y.Z-beta.Nfails the gate. - CHANGELOG — the bump PR must contain a
## [X.Y.Z-beta.N] - datesection; it may be manually curated withapply --betaor generated withapply --beta --notes. The release body is extracted from this committed section; the dispatch fails if it is missing and does not regenerate notes. - Tag — the immutable tag
vX.Y.Z-beta.Nis created on the dispatch target SHA. Beta creates no GitHub Release: the official Zenodo ↔ GitHub integration archives every Release (pre-releases included), so a beta Release would add an unwanted version to the Zenodo family. The git tag alone backs by-tag recovery. npm publish --tag betapublishes the immutable artifact. The workflow does not create a PR comment.
Recovery / Failure Handling¶
Beta npm-publish recovery (explicit dispatch)¶
If a beta's git tag already exists but npm publishing failed, rerun Release
with recovery_version (the committed X.Y.Z-beta.N, without v) and
recovery_target_sha (the full 40-hex commit SHA). The legacy
X.Y.Z-beta.<pr>.<sha7> format is still accepted but additionally requires
recovery_pr_number matching the version and the seven-character SHA suffix.
For the current X.Y.Z-beta.N format only the version and SHA are needed. The
workflow checks these values before checkout, requires the remote v<version>
tag to exist on the recovery target SHA, and never creates or moves a tag or
release in this mode (beta creates no GitHub Release, so recovery is bound to
the tag alone). It packs the immutable checkout and publishes only when that
exact npm version is absent; an existing npm version is a successful no-op.
Partial or invalid inputs, a missing tag, API errors, and tag mismatches fail
closed.
The recovery path is beta-only and does not calculate a new version or change the normal stable dispatch and beta-channel dispatch paths.
The pipeline is designed so reruns are safe:
- Already fully released → the idempotent guard exits 0; nothing is re-tagged, re-released, or re-published.
- Crash between tag push and release create (stable) → tag exists but release is missing; a rerun skips tag creation and completes the release. Beta creates no Release, so its reruns proceed to the npm step.
- Crash after npm publish → a rerun hits the idempotent guard (exit 0), and the npm existence check prevents publishing the same version again.
- changelog-extract fails on a stable or beta dispatch → the
[X.Y.Z]/[X.Y.Z-beta.N]section is missing fromCHANGELOG.md; add it in the bump PR and rerun. Both non-recovery channels extract the release body from the committedCHANGELOG.md; recovery extracts the section at the recovery target (the static note is the last resort for tags predating the section). - Gate (e) rejects the section format → the committed section violates the
canonical format (
scripts/changelog-format.mjs); fix the section in a follow-up PR and rerun. CI catches the same violations on every PR vianpm run docs:check-changelog. - Re-run reports "body diverges from the canonical CHANGELOG section" →
the published release body was hand-edited after creation. Restore it with
gh release edit <tag> --notes-file release-artifact/release-notes.mdfrom the failed run's artifact, or fix the CHANGELOG and dispatch a recovery.
Before a manual rerun, verify the expected pre-run state (git tag, GitHub
releases, and the npm version) directly against the live registries.
npm Policy¶
Deprecate, never unpublish. A published package version is permanent —
removing it breaks downstream installs and the npm_check idempotency gate.
To retire a broken version:
npm deprecate pantheon-opencode@<ver> "reason: <why it should not be used>"
Rollback¶
Manual step with human approval. The release workflow never rolls back — it publishes forward only. Re-pointing the npm
latesttag is decided and executed by a maintainer, outside the automated path.
A rollback re-points the latest dist-tag. It does not delete the released
artifact and it does not rewrite history.
Trigger¶
Roll back when a blocking defect is discovered after the stable publication
and latest carries a regression that prevents use — for example an installer
that cannot complete, or a package that does not start on the supported OpenCode
line. A defect that can wait for the next patch does not qualify: publish
forward instead.
Restore the stable channel¶
npm dist-tag add pantheon-opencode@1.5.2 latest
Syntax: npm dist-tag add <package-spec (with version)> [<tag>]
(npm dist-tag --help).
1.6.0 remains published on npm — only the latest pointer moves back to
1.5.2. Consumers without a lockfile resolve 1.5.2 again, while the
regressed version stays reachable by exact version. Nothing is re-tagged on
git, and no workflow runs.
Do not¶
- Do not
npm unpublish. Unpublishing is destructive and irreversible: it breaks every consumer whose lockfile pins the affected version, and it defeats thenpm_checkidempotency gate. Versions are deprecated, never removed (see npm Policy). - Do not rewrite the GitHub Release without a note. The Release is the published record of what shipped; editing or deleting it silently hides the incident from everyone who reads the changelog later.
What a rollback does not undo¶
- Zenodo archival — once the GitHub Release exists, the Zenodo integration has deposited the record and version DOI. That deposit is irreversible.
- The git tag —
v1.6.0stays on its commit. The tag is immutable and is not moved or deleted during a rollback.
Required record¶
Log the rollback on the release (or the tracking issue) before or immediately after the command runs:
- the defect that triggered it, with evidence;
- the command executed, verbatim;
- the resulting
npm view pantheon-opencode dist-tagsoutput.
Without that record, a later reader cannot tell a rollback apart from a failed publication.
Retiring the next dist-tag¶
Manual step with human approval. Not part of the automated release workflow.
next was the pre-stable preview channel. Once stable v1.6.0 is published and
verified it has no remaining purpose, and leaving it in place invites new
releases to be tagged into a channel nobody resolves. It is removed exactly
once.
Prerequisite: the post-publication verification of the stable release
passed — npm view pantheon-opencode dist-tags reports latest = 1.6.0, and
installing pantheon-opencode@1.6.0 from the public registry works. Removing
next before that check leaves consumers who follow next without a
resolution target while the stable channel is still unproven.
# Only after the post-publication verification passed.
npm dist-tag rm pantheon-opencode next
# Prove the result: latest = 1.6.0, beta preserved, next absent.
npm view pantheon-opencode dist-tags
Syntax: npm dist-tag rm <package-spec> <tag> (npm dist-tag --help).
The removal only drops a tag — no published version is deleted. beta
continues to point at the beta line and is not touched by this step.
Branch protection (main)¶
The main protection policy — required checks, admin bypass, and the manual
enable/verify procedure — lives in Branch Protection.
The release job still re-runs the six gates on the frozen TARGET_SHA;
protection does not replace them.
Pre-Release Checklist¶
Before cutting a release, verify:
- [ ]
node scripts/versioning.mjs statusshows a pending release (tag < pkg) - [ ]
CHANGELOG.mdhas a## [X.Y.Z] - dateentry for the new version - [ ] Version manifests match:
package.json==plugin.json==pyproject.toml==src/plugins/tui/package.json - [ ] All required checks green on the bump PR and on the push run for the
merged
mainSHA (validate,test-suite,plugin-v2-ts-coverage,commitlint,security-scan,CodeQL) - [ ] The six release gates are expected to PASS for the frozen
TARGET_SHA; the dispatch'svalidatejob is the authority (it re-runs all six) - [ ]
npm run release:dry-runpasses (status + pack)
Consumption Options¶
| Method | Best for | How |
|---|---|---|
| npm package | Dev workflow / CI | npm install pantheon-opencode (stable) or npm install pantheon-opencode@beta |
| Pantheon Installer | New / existing projects | npx pantheon-opencode init |
| GitHub Release | Downloads / CI | Source archives from Releases page |
| GitHub Template | New projects | "Use this template" on GitHub |
| Git clone + copy | Selective setup | git clone and copy only what you need |
Release Assets¶
Each release includes:
| Asset | Description |
|---|---|
Source code (zip) |
GitHub auto-generated |
Source code (tar.gz) |
GitHub auto-generated |
pantheon-opencode@<ver> on npm |
Published with latest (stable) or beta dist-tag, provenance-signed |
Preserved Releases: Zenodo¶
Zenodo preserves releases for citation and long-term
access through the official Zenodo ↔ GitHub integration on
ils15/pantheon-opencode. Each
published GitHub Release is archived automatically as a new version, giving that
release a version DOI; all versions share the stable concept DOI
10.5281/zenodo.22650136
(conceptrecid 22650136), which always resolves to the latest archived release.
The integration has no pre-release filter: it archives every GitHub Release. Only the stable channel creates a GitHub Release, so only stable versions are archived. Beta releases create a git tag and publish to npm but no Release, and are therefore intentionally absent from the Zenodo family.
.zenodo.json is the source of the deposited metadata
(title, creators/ORCID, description, license, keywords, and related
identifiers). scripts/versioning.mjs bumps its version, publication_date,
and url alongside the other manifests on every release, so the file must stay
in sync for the next archive. The deposited title is read from .zenodo.json
at the tagged commit and is not applied retroactively to versions already
archived.
The integration is configured in Zenodo and runs on Zenodo's side — no workflow, token, or protected environment is stored in this repository. If a Release is not archived automatically, trigger a sync from the repository's Zenodo GitHub settings, then verify the concept DOI, the per-release version DOI, and the record metadata on Zenodo.