Skip to content

Release process

CSRetro uses SemVer in the repo-root VERSION file. CMake reads it for PROJECT_VERSION and CPack package names. Human-readable history lives in CHANGELOG.md.

Automation

Piece Role
.github/workflows/release-please.yml On pushes to main, opens or updates a Release PR that bumps VERSION, updates CHANGELOG.md, and updates .release-please-manifest.json. After it creates a GitHub Release (or after the merge fallback tags main), it starts release.yml via workflow_dispatch so CPack runs even when GITHUB_TOKEN would not trigger a tag push workflow.
.github/workflows/release.yml Runs when a version tag v* is pushed, when Release Please dispatches it with that tag, or when a maintainer runs it manually (Actions → Release → Run workflow) with an existing tag: builds CPack archives on Linux (x64 + arm64), Windows (x64), and macOS (x64 + arm64), then attaches them to the GitHub Release.
.github/workflows/docs.yml Deploys the MkDocs handbook to GitHub Pages on pushes to main (not tied to version tags).

Configuration for release-please: release-please-config.json (release-type: simple, version-file: VERSION).

Conventional commits

Release-please infers the next version from Conventional Commits on main (e.g. feat: → minor, fix: → patch). Use clear, scoped messages so release notes group correctly.

GitHub’s default GITHUB_TOKEN does not trigger new workflow runs for events it creates (e.g. tags from an action). So after merging a Release PR, the tag created by release-please might not start release.yml automatically.

Recommended (optional for CPack): add a repository secret RELEASE_PLEASE_TOKEN (fine-grained or classic PAT). Release Please now dispatches release.yml after creating a release, so download packages no longer depend only on tag-push events. A PAT still helps when GitHub blocks Release PR creation for GITHUB_TOKEN, and it restores classic tag-push behaviour if you prefer that path. For a classic PAT, the repo scope is usually enough. For a fine-grained PAT, grant Contents and Pull requests on this repository (read/write as offered). The workflow uses:

secrets.RELEASE_PLEASE_TOKEN || github.token

so CI can run without the secret, but opening the Release PR and tag-triggered release builds are reliable when the PAT is set (see troubleshooting below).

Troubleshooting

release-please failed: GitHub Actions is not permitted to create or approve pull requests

The workflow already requests contents: write and pull-requests: write in .github/workflows/release-please.yml. If the job still fails with this message:

  1. Repository settings (no PAT): On GitHub → Settings → Actions → General → Workflow permissions, choose Read and write permissions and enable Allow GitHub Actions to create and approve pull requests. If the organization enforces stricter defaults, an org owner may need to allow this for the repository or you must use a PAT.

  2. Personal access token (recommended): Add the repository secret RELEASE_PLEASE_TOKEN as in Personal access token (recommended) above. A PAT is not subject to the same GITHUB_TOKEN policy limits and also fixes workflows that do not run on tags created by Actions.

  3. Workflow fallback (no GitHub UI change): .github/workflows/release-please.yml runs Release Please with continue-on-error. If opening the Release PR fails but the branch release-please--branches--main was updated, the workflow merges that branch into main using the Git merge API (only needs contents: write), then creates the v* tag and GitHub Release from VERSION, then dispatches release.yml so CPack artifacts are built without relying on tag-push events. A PAT is still useful if you want other repos or the same repo to see conventional tag pushes outside Actions.

No tag and no CPack artifacts (Linux / Windows / macOS)

Automation needs either a merged Release PR (release-please) or a manually pushed v* tag to run .github/workflows/release.yml.

Fix the pipeline (one-time): enable workflow permissions and optional PAT so Release Please can open its PR again. Merge that PR when ready so release-please can create the tag and GitHub Release (use RELEASE_PLEASE_TOKEN so the tag push triggers release.yml).

Recover without waiting for Release Please: if main already has the right VERSION / changelog state:

  1. Create and push an annotated tag from your machine (or GitHub UI → Releases → Draft from tag):

bash git fetch origin git checkout main git pull # Ensure VERSION matches the tag you are about to create, e.g. 1.2.3 → v1.2.3 git tag -a vX.Y.Z -m "vX.Y.Z" git push origin vX.Y.Z

  1. Confirm the Release workflow runs on GitHub (Actions → Release). If it did not start (rare), open Actions → Release → Run workflow, enter the same vX.Y.Z tag, and run. That uses workflow_dispatch to build and upload CPack artifacts for all platforms.

Maintainer checklist

  1. Merge feature PRs on main using conventional commits where possible.
  2. Wait for the Release please PR; review VERSION / CHANGELOG.md / manifest changes.
  3. Merge the Release PR when you want to ship that version.
  4. Confirm the GitHub Release and vX.Y.Z tag exist; confirm release.yml completed and CPack artifacts are attached.
  5. If the handbook should mention the release prominently, update audience pages only when behavior or defaults change (see Contributing).

Rollback

If a bad Release PR was merged: fix forward with a new PR (preferred). Reverting the merge is possible but coordinate with tags/releases on GitHub to avoid confusion. Do not rewrite public tags that users may have pinned.