Release

Cutting a new libYSE release

A release is irreversible (the tag, the GitHub release artefact, and the downstream binding regenerations all assume the version went out the door and stayed there). This skill drives the workflow end-to-end with a single confirmation gate at the start.

Authoritative version source: YseEngine/system.hpp line const std::string VERSION = "X.Y.Z";. Everything else — Sphinx conf.py, dist/ archive names, the GitHub release title — derives from that string.

Tools the skill drives

• python yse.py release patch|minor|major — bumps VERSION in system.hpp, commits Release vX.Y.Z, tags vX.Y.Z, pushes both. Requires clean tree and current branch in {master, dev}. Only runs the bump on master — see step 5.
• .github/workflows/release.yml — fires on v* tag push. Builds Linux x64, Windows x64, and Android multi-ABI archives; publishes them as GitHub release assets.
• .github/workflows/build.yml, benchmark.yml, documentation.yml — the dev→master PR triggers these; we wait for green before merging.

Procedure

1. Ask the user which bump kind

The trigger phrase rarely specifies. Prompt:

Patch (X.Y.Z+1) / Minor (X.Y+1.0) / Major (X+1.0.0) — which?

Use AskUserQuestion with the three options and one "Other" for raw input (e.g. they want to skip a number, which yse.py release does not support and would have to be done manually).

2. Pre-flight on dev

git checkout dev
git pull --ff-only origin dev
git status --porcelain   # must be empty

Read YseEngine/system.hpp to get the current version. Compute the new version. Confirm the tag does not already exist (git tag -l vX.Y.Z and gh api repos/:owner/:repo/releases/tags/vX.Y.Z — the second catches remote-only tags).

3. C API drift audit

The Dart bindings (and any other FFI consumer) are generated from YseEngine/c_api/include/yse_c/*.h in a separate repository. If new public C++ surface landed since the last release but wasn't mirrored into the C bridge, downstream bindings will silently miss it. To catch this:

1. Find the last release commit: git log v$LAST..HEAD -- YseEngine/ ':!YseEngine/c_api' — public headers (*.hpp not in internal/ / implementations/ / synth/) and yse.hpp that changed.
2. Inspect each changed header. Look for:
   • New public methods on classes already exposed via yse_c/yse_*.h
   • New public free functions / accessors
   • New enum values in YseEngine/headers/enums.hpp (compile-time yse_enums_check.cpp will catch missing mirrors, but only if a build runs — see step 4)
3. For each suspected drift, hand off to the c-api-extend skill (/c-api-extend) — it knows the conventions. Do NOT inline a wrapper yourself unless it is a single trivial accessor.
4. If drift exists and the user wants to ship the release before fixing it, document the gap in the release notes ("known to be missing from C API in this version").

3b. API-reference coverage audit (docs drift)

The Sphinx API reference enumerates C headers explicitly — documentation/source/api/c_api.rst carries one doxygenfile directive per yse_c/*.h header — so a brand-new header never appears on the docs site by itself. (This bit the v2.3.x cycle: yse_clip.h, yse_python.h, and yse_bus.h were all missing until the pre-v2.3.2 audit.) Check:

for h in YseEngine/c_api/include/yse_c/*.h; do
  grep -q "$(basename "$h")" documentation/source/api/c_api.rst \
    || echo "MISSING from c_api.rst: $(basename "$h")"
done

Every hit is a doc gap: add a matching doxygenfile block (under a fitting section heading) in the release-prep PR (step 5).

The C++ pages have the same failure mode at class granularity: for each new public class step 3 surfaced, confirm it renders somewhere under documentation/source/api/*.rst (a genuinely new subsystem needs a new page plus an index.rst toctree entry). There is no mechanical check for this side — use step 3's changed-header list as the worklist.

4. Build sanity + enum mirror check

python yse.py build --release

A successful release-config build with YSE_BUILD_C_API=ON (the default) implies yse_enums_check.cpp passed at compile time — enum mirrors in yse_c/yse_enums.h are consistent with YseEngine/headers/enums.hpp. If the build fails on yse_enums_check.cpp, the enums drifted; fix them before continuing.

5. Refresh README and PROJECT_OVERVIEW.md (on dev, in a release-prep PR)

Branch: release/vX.Y.Z-prep from dev.

• README.md — only update the # libYSE X.Y header if the major or minor bumped (patch releases don't touch the README header). Skip on patch.
• PROJECT_OVERVIEW.md — delegate to the project-overview-update skill workflow (read meta header SHA, diff against HEAD, decide partial vs full). On a patch release this is usually a no-op or a small section touch; on a minor/major it is more often a partial rewrite of a few sections.
• Sphinx conf.py reads VERSION from system.hpp automatically (per PR #89) — do not edit documentation/ for the version. Only touch documentation/source/ to close API-reference coverage gaps found in step 3b (missing doxygenfile directives or pages), or if a code change in this release also changed user-facing behaviour that the intro/tutorials describe.

Commit the prep PR with message:

release-prep vX.Y.Z: refresh README and overview

Push and open the PR with gh pr create --base dev.

6. Wait for prep-PR CI, merge to dev

Use gh pr checks --watch on the prep PR. When green, merge:

gh pr merge --merge --auto <pr-number>

(Or --squash if the project convention is squash; check existing release-prep PRs for the pattern. Looking at recent history, --merge matches the existing style.)

7. Promote dev → master

gh pr create --base master --head dev \
  --title "Release vX.Y.Z" \
  --body "<short summary of what's in this release>"

Wait for CI on this PR too (gh pr checks --watch). When green, merge with --merge (release commits should stay individually identifiable on master — do not squash).

8. Run the bump and route it through a release PR

master is a protected branch — direct pushes are rejected, including the one yse.py release would attempt. The bump has to land via PR. The local-side prep mirrors what yse.py release does but stops short of pushing to master:

git checkout master
git pull --ff-only origin master
python yse.py release patch|minor|major    # creates the bump commit + local tag,
                                            # then fails at `git push` due to branch protection

The push failure is expected — yse.py release does not yet know about branch protection. Recover by moving the bump commit onto a release branch and discarding the local tag (the tag has to land on the merge commit, not the bump commit; matches the existing v2.1.0/v2.0.2 pattern):

git checkout -b release-vX.Y.Z      # carries the new "Release vX.Y.Z" bump commit
git branch -f master origin/master  # rewind local master to the unbumped origin tip
git tag -d vX.Y.Z                   # the tag goes on the merge commit later, not the bump
git push -u origin release-vX.Y.Z

Open the bump PR (this is the second PR in the release path; the first was step 7's dev → master promotion). Title is the same as the step-7 PR for searchability — it shows up as e.g. "Release v2.1.1" in both PR lists.

gh pr create --base master --head release-vX.Y.Z \
  --title "Release vX.Y.Z" \
  --body "Version bump for the vX.Y.Z release. Routed through a PR because branch protection on master requires it (same path as release-v2.1.0 \\u2192 PR #87)."

Wait for CI (gh pr checks --watch). When green, merge with --merge.

Pull master, then tag the merge commit (not the bump commit) — this matches how v2.1.0 was tagged (git show v2.1.0 → points at PR #87's merge commit, not at 54d1d96 Release v2.1.0):

git checkout master
git pull --ff-only origin master
git tag vX.Y.Z $(git rev-parse origin/master)
git push origin vX.Y.Z

The release.yml workflow fires on the v* tag push and builds + publishes the GitHub release.

Skill follow-up: yse.py release is mid-way: it bumps and tags locally but cannot push to a protected master. Either teach it about branch protection (open the release PR itself, wait, merge, tag the merge commit) or split it into two subcommands (release-bump that just bumps + commits on the current branch, and release-tag that tags an arbitrary commit and pushes the tag). Until that lands, the dance above is the manual fallback.