From 47eeb9d36c882b3ed0966efc40beb4ca5b71d1a6 Mon Sep 17 00:00:00 2001 From: shawn Date: Mon, 8 Jun 2026 22:23:10 +0800 Subject: [PATCH 1/2] docs: align release workflow with PR-only master rule Remote master enforces "changes must go through a pull request" (GH013), so version bumps can't be pushed directly to master as the old instructions claimed. Rewrite the version-bump section: bump via its own standalone PR, then push the vX.Y.Z tag separately after merge (tags aren't covered by the branch rule). Also note that release.yml publishes to crates.io, not just GitHub Releases. Co-Authored-By: Claude Opus 4.8 (1M context) --- CLAUDE.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 4a6668e..b14cc61 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -40,16 +40,18 @@ Add it as a Makefile target first, then reference the target from CI. Never let If you notice you're on `master` with uncommitted changes, stash them, switch to a new branch, and pop the stash before committing. -### Exception: version bumps +### Version bumps (also via PR) -Version bumps are the **only** allowed direct-to-`master` commits. They must not ride along inside a feature/fix PR — keep them as standalone commits so the release history stays readable. +Remote `master` enforces a **"changes must be made through a pull request"** rule, so there are **no** direct-to-`master` pushes — version bumps included (a `git push origin master` is rejected with `GH013`). Keep the bump as its **own** standalone PR; never let it ride inside a feature/fix PR, so the release history stays readable. When the feature/fix PRs that make up a release have all merged into `master`: 1. `git checkout master && git pull` to land on the merged tip. -2. Edit `Cargo.toml` (and `Cargo.lock` — `cargo build` will refresh it) to the new version. -3. Lock the `CHANGELOG.md` `[Unreleased]` section to `[X.Y.Z] - YYYY-MM-DD`. -4. `git commit -m "chore: bump version to X.Y.Z"` on `master`. -5. `git tag vX.Y.Z` and `git push origin master --follow-tags`. - -The `release.yml` workflow triggers on `v*` tag pushes and produces the GitHub Release (cross-platform binaries + checksums). Pushing the tag is therefore both the version stamp **and** the release trigger — no extra step. +2. Branch off, e.g. `chore/bump-X.Y.Z`. +3. Edit `Cargo.toml` (and `Cargo.lock` — `make build` refreshes it) to the new version. +4. Lock the `CHANGELOG.md` `[Unreleased]` section to `[X.Y.Z] - YYYY-MM-DD`. +5. Commit `chore: bump version to X.Y.Z`, push the branch, open a PR, and squash-merge it once CI is green. +6. `git checkout master && git pull` to land on the squashed bump commit. +7. `git tag -a vX.Y.Z -m "termdown X.Y.Z"` on that commit and `git push origin vX.Y.Z`. + +Tags are **not** covered by the branch-protection rule (it guards `refs/heads/master` only), so the tag push in step 7 succeeds directly — this is the one push that doesn't go through a PR. The `release.yml` workflow triggers on `v*` tag pushes and produces the GitHub Release (cross-platform binaries + checksums) **and** publishes to crates.io (`cargo publish`). Pushing the tag is therefore the release trigger; the version stamp itself lands earlier via the bump PR. From 1b52e5ed8b5fecb50086272d2822d90a61f309bb Mon Sep 17 00:00:00 2001 From: shawn Date: Mon, 8 Jun 2026 22:29:16 +0800 Subject: [PATCH 2/2] chore: bump action-gh-release v2 -> v3 (Node 24 runtime) softprops/action-gh-release@v2 runs on the deprecated Node 20 runtime; v3.0.0 moves to Node 24 with no input/behavior changes. The other actions (checkout@v6, upload-artifact@v7, download-artifact@v8, rust-cache@v2) are already on their latest major and Node 24. Co-Authored-By: Claude Opus 4.8 (1M context) --- .github/workflows/release.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 4ab93fe..93db941 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -97,7 +97,7 @@ jobs: cat SHA256SUMS - name: Create GitHub Release - uses: softprops/action-gh-release@v2 + uses: softprops/action-gh-release@v3 with: generate_release_notes: true files: |