The Engineer

Appearance

Cutting a Release ​

How the maintainer cuts a SemVer GitHub release. One deliberate action; everything mechanical after it is automated. Releases ship as GitHub releases (npm publish is deferred), consistent with the README Versioning section.

How to cut a release ​

Actions tab → Release workflow → Run workflow → pick the bump level (patch / minor / major), optionally tick dry_run → Run.

The run gates first (pnpm lint + bundled-docs sync + pnpm test + pnpm build), then computes the new version from package.json, commits the bump to main, pushes an annotated vX.Y.Z tag, and publishes a GitHub Release with auto-generated notes. If the gate fails it aborts with no tag and no release. Notes are generated by GitHub (grouped by PR/author) and need no Conventional Commit prefixes.

Only the repository owner can trigger it (workflow_dispatch requires write access). The bump commit lands on main and harmlessly re-triggers CI and the docs deploy.

Choosing the bump level ​

PATCH is the default lane; MINOR and MAJOR are deliberate and infrequent.

  • PATCH — backward-compatible fix or polish: bug fix, docs, refactor, perf, dependency bump. Nothing new, nothing breaks.
  • MINOR — new backward-compatible capability: a new plugin or adapter, a new pipeline sub-phase, a new CLI command or flag. Existing setups keep working untouched.
  • MAJOR — breaking change a user or plugin author must act on: an incompatible change to an adapter contract (TriggerAdapter / CommunicationAdapter / AgentAdapter / GitHostingAdapter — the primary public API for plugin authors), a config-schema break, a removed or renamed CLI command, or anything requiring re-setup or migration.

One-time RELEASE_PAT setup ​

The bump commit pushes to protected main, which the default GITHUB_TOKEN cannot do. The workflow checks out with a RELEASE_PAT secret instead, so pushes act as the owner.

Create a fine-grained PAT (GitHub → Settings → Developer settings → Fine-grained tokens): resource owner FarzamMohammadi, this repository only, Repository permissions → Contents: Read and write (nothing else), 90-day expiry. Save it as the repository Actions secret named RELEASE_PAT (repo → Settings → Secrets and variables → Actions). Renew it every 90 days; a release that fails with an auth or permission error means the PAT has lapsed.

If a run dies after the tag is pushed but before the release is created, finish it with gh release create <tag> --verify-tag --generate-notes rather than re-running (a re-run would compute the next version).

dry_run ​

Tick dry_run to gate, compute the version, and preview the release notes (in the run summary) without creating any commit, tag, or release. Use it to sanity-check before a real release. It does not exercise the protected-main push, so the first real run is what proves the RELEASE_PAT wiring.