Skip to content

RELEASE.md

Latest commit

 

History

History
138 lines (110 loc) · 5.19 KB

RELEASE.md

File metadata and controls

138 lines (110 loc) · 5.19 KB
Raw

Release runbook

Release actions begin after the candidate gate passes and the exact mutation is explicitly approved.

Release channels

Package version npm dist-tag GitHub release Stable latest
x.y.z latest Full release, marked latest Moves to x.y.z
x.y.z-<prerelease> next Prerelease Remains on current stable

scripts/release-version.ts is the executable channel contract. It accepts an exact SemVer version without build metadata, emits the Git tag and release channel, and is covered by unit tests. Release commands use its output directly.

The current native-discovery candidate is 1.0.0-rc.2. Its canonical opt-in, test matrix, and feedback tracker is #34.

Release gate

Before proposing a release:

  1. Review every open PR and record a merge, close, or hold recommendation.
  2. Confirm the feature-parity matrix and intentional compatibility changes.
  3. Confirm package.json, package-lock.json, and docs/releases/v<version>.md name the exact candidate.
  4. Run npm run release:check.
  5. Confirm the minimum and current OpenCode CLI smoke, ACP stdio, and every plugin-facing Microsoft TUI Test view pass from source.
  6. Confirm npm audit reports no vulnerabilities.
  7. Confirm npm pack --dry-run contains only current build artifacts.
  8. Test the packed tarball in a clean temporary project, including ACP.
  9. Verify the worktree and branch are exactly the reviewed revision.
  10. For prereleases, verify npm latest points to the current stable version.
  11. Show the user the evidence and exact commands that will mutate GitHub/npm.
  12. Wait for explicit approval before any commit, push, tag, GitHub release, or npm publish action.

Local preflight

npm run release:check
npm run smoke:opencode
npm run smoke:opencode:acp
npm run test:tui:check

The preflight is intentionally non-releasing. It validates the version/channel contract and release-notes file, then runs validation, coverage, security audit, and package preview. The OpenCode smoke and TUI screenshot checks remain separate explicit gates locally and in CI.

npm trusted publisher

The release workflow uses GitHub OIDC and npm provenance. The package must have exactly one trusted publisher matching this repository, workflow, and GitHub environment:

npx --yes npm@11.16.0 trust list opencode-lmstudio
npx --yes npm@11.16.0 trust github opencode-lmstudio \
  --file release.yml \
  --repository agustif/opencode-lmstudio \
  --environment release \
  --allow-publish

Configuring trust requires npm package-owner authentication and 2FA. CI authentication is OIDC-only. Use npm 11.16.0 or newer so the trust command includes the registry's required explicit publish permission.

Release workflow

The manual GitHub Actions workflow is the canonical mutation path. It defaults to validation-only.

Validation-only run:

gh workflow run release.yml \
  --ref main \
  -f version=<version> \
  -f publish=false

Approved publication run:

gh workflow run release.yml \
  --ref main \
  -f version=<version> \
  -f publish=true

For every candidate the workflow:

  1. validates exact SemVer, manifest version, release notes, branch, and clean tree;
  2. runs core, minimum/current OpenCode smoke, ACP stdio, all TUI views, audit, and package gates;
  3. installs the packed candidate, serves it from an isolated local registry, and repeats the real OpenCode smoke, native resolver/cache, ACP, and TUI matrix before publication;
  4. stages a draft GitHub release, marking prereleases before publication;
  5. publishes with npm provenance to derived tag next or latest;
  6. verifies that the derived npm tag resolves to the exact version and stable latest remains unchanged for a prerelease;
  7. anonymously installs the exact public npm version and repeats the real OpenCode smoke, ACP, and every TUI view;
  8. gives the exact npm spec directly to minimum and current OpenCode, verifies their package resolver/cache plus chat, and repeats ACP from that resolver; and
  9. finalizes the GitHub prerelease or full latest release.

If npm publication fails, the workflow removes the staged draft release and tag. If npm succeeds but later verification fails, preserve the draft and published package for explicit reconciliation; npm versions are immutable.

Post-release verification

npm view opencode-lmstudio dist-tags --json
npm view opencode-lmstudio@<version> version dist.tarball dist.integrity --json
gh release view "v<version>" --json tagName,isDraft,isPrerelease,url
npm run smoke:opencode:resolver -- opencode-lmstudio@<version>
npm run smoke:opencode:acp:package -- opencode-lmstudio@<version>
git status --short --branch

For a prerelease, also prove that opencode-lmstudio@next resolves to the candidate and opencode-lmstudio@latest still resolves to the current stable version. Download the registry tarball, inspect it, and install/import it in a clean temporary project before calling the release complete.

Update the canonical feedback tracker with immutable npm and GitHub links after publication. Publish final 1.0.0 as a separate immutable version after RC feedback is triaged.