---
title: "Releasing"
source: "docs/releasing.md"
---

> Part of [botgumi docs](https://botgumi.com/docs/llms.txt). Every page: [llms.txt](https://botgumi.com/llms.txt).

# 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:

```bash
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:

```bash
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.