botgumi

Guides

Releasing

botgumi has one version: the template version. Every @botgumi/* package shares it (a Changesets fixed group), the Swift package is consumed by its git tag, and each generated app records it in .botgumi.json. A release is a git tag vX.Y.Z plus a GitHub release with notes.

Day to day: add a changeset

Every PR that changes a package adds a changeset:

pnpm changeset

Pick the bump by what changes for an app that upgrades:

Bump When Example
major An app must change code or config to upgrade An interface method is renamed; a config key moves
minor New capability, nothing breaks A new adapter, a new CLI command, a new agent rule
patch A fix with no new surface A contract test that was too loose; a typo in a role file

Before v1, breaking changes go out as minor (semver for 0.x). Write the summary for the person upgrading an app: what changed and what, if anything, they must do. It becomes the release note.

Docs-only and site-only PRs need no changeset.

What the release workflow does

.github/workflows/release.yml runs on every push to main:

  1. Changesets pending: it opens or updates a PR titled chore: release. That PR bumps every package to the next version and writes each package's CHANGELOG.md. Review it like any PR.
  2. No changesets pending (the release PR just merged): pnpm release (scripts/release.ts) reads the version, and if vX.Y.Z is not tagged yet, tags it, pushes the tag and creates the GitHub release. The notes are built from the changelogs, grouped as breaking changes, features and fixes.

A human merges the release PR, as with every PR in this repo. Nothing is published to npm: the packages are private.

Preview the notes for the current version without tagging anything:

node scripts/release.ts --dry-run

Where releases show up

  • GitHub releases and tags. SwiftPM resolves from: "0.1.0" against the v0.1.0 tag.
  • botgumi.com/releases. The site reads the same changelogs at build time; a change to any CHANGELOG.md on main redeploys it (Cloudflare Workers Builds, see site/README.md).
  • Apps. The upgrade bot (not built yet) opens a PR in each app when a new version is tagged.

Known limits

  • The workflow needs the repo setting Actions → General → Allow GitHub Actions to create and approve pull requests; without it the release PR is never opened.
  • The release PR is opened with the workflow's GITHUB_TOKEN, so GitHub does not run CI on it. Push an empty commit to it, or give the workflow a GitHub App token (docs/github-app-setup.md).
  • scripts/release.ts takes the version from @botgumi/cli. That is safe because the fixed group keeps every package on the same version.