| 1 |
--- |
| 2 |
name: cut-release |
| 3 |
description: Cut a new versioned release of bpftop — pick the version, open a version-bump PR, sign-tag the merge commit on main, and draft GitHub release notes in the project's established format. Use whenever the user says "cut a release", "release X.Y.Z", "ship X.Y.Z", "time to release", "tag a new version", "bump to X.Y.Z", "let's do a release", or otherwise initiates a release. Trigger even when the user only asks for one step ("what version should we bump to?", "make the release PR", "tag it") — load this skill so the broader workflow context is available, and only do the step the user asked for. |
| 4 |
--- |
| 5 |
|
| 6 |
# Cut a release |
| 7 |
|
| 8 |
This is the bpftop release runbook. Five steps: pick the version, open the bump PR, wait for merge, push a signed tag, fill in the release notes. |
| 9 |
|
| 10 |
Tags and releases are user-visible and permanent. Confirm the version, the tag SHA, and the release notes content with the user before pushing the tag and before publishing the draft. |
| 11 |
|
| 12 |
--- |
| 13 |
|
| 14 |
## Step 1: Pick the version |
| 15 |
|
| 16 |
```bash |
| 17 |
git log $(git describe --tags --abbrev=0)..HEAD --oneline |
| 18 |
``` |
| 19 |
|
| 20 |
bpftop is pre-1.0. Apply semver: |
| 21 |
|
| 22 |
- **Patch** (`0.x.y` → `0.x.(y+1)`) — only fixes, refactors, dep bumps |
| 23 |
- **Minor** (`0.x` → `0.(x+1)`) — any new user-facing feature, or any breaking change to CLI flags / TUI keybindings / output format |
| 24 |
|
| 25 |
CI churn, AI-assistant config tweaks, and dependabot bumps that don't change runtime behavior are not on their own a reason to cut a release. |
| 26 |
|
| 27 |
Tell the user which commits drove the decision and let them confirm or override. |
| 28 |
|
| 29 |
### When the user asks about going to 1.0 |
| 30 |
|
| 31 |
The signal is UX/API stability, not feature completeness. Recommend 1.0 once the user is willing to commit that the next release won't break CLI flags or TUI keybindings without a deprecation cycle, the feature surface is additive (no "initial X" support, no churning subsystems), and they'd be comfortable with a distro packaging it. When something just landed in the prior release labeled "initial", recommend one more minor first. |
| 32 |
|
| 33 |
--- |
| 34 |
|
| 35 |
## Step 2: Open the bump PR |
| 36 |
|
| 37 |
```bash |
| 38 |
git checkout -b release/X.Y.Z |
| 39 |
``` |
| 40 |
|
| 41 |
Edit `Cargo.toml`: |
| 42 |
|
| 43 |
```toml |
| 44 |
[package] |
| 45 |
name = "bpftop" |
| 46 |
version = "X.Y.Z" |
| 47 |
``` |
| 48 |
|
| 49 |
Refresh the lockfile: |
| 50 |
|
| 51 |
```bash |
| 52 |
cargo update -p bpftop --precise X.Y.Z |
| 53 |
``` |
| 54 |
|
| 55 |
The diff should be exactly two lines: one in `Cargo.toml`, one in `Cargo.lock`. Verify before committing. |
| 56 |
|
| 57 |
Commit format is strict and minimal — subject only, **no body**, with a `Signed-off-by` trailer: |
| 58 |
|
| 59 |
```bash |
| 60 |
git commit -s -m "chore: bump version to X.Y.Z" |
| 61 |
``` |
| 62 |
|
| 63 |
No commit body. Release notes live on the GitHub release page, not in the bump commit. This is a project convention — past releases (e.g. v0.8.0 commit `aab2d53`) follow this minimal pattern, and duplicating context here is noise. |
| 64 |
|
| 65 |
Push and open the PR with an **empty body**: |
| 66 |
|
| 67 |
```bash |
| 68 |
git push -u origin release/X.Y.Z |
| 69 |
gh pr create --title "chore: bump version to X.Y.Z" --body "" |
| 70 |
``` |
| 71 |
|
| 72 |
Do not merge the PR. Wait for the user to merge it. |
| 73 |
|
| 74 |
--- |
| 75 |
|
| 76 |
## Step 3: Wait for merge and green CI |
| 77 |
|
| 78 |
```bash |
| 79 |
gh pr view <N> --json state,mergeCommit,statusCheckRollup |
| 80 |
``` |
| 81 |
|
| 82 |
Look for `state: MERGED` and all checks `SUCCESS` (`build_and_test` on x86_64 and aarch64). Capture `mergeCommit.oid` — that's what gets tagged. |
| 83 |
|
| 84 |
--- |
| 85 |
|
| 86 |
## Step 4: Cut the signed annotated tag |
| 87 |
|
| 88 |
```bash |
| 89 |
git checkout main && git pull --ff-only origin main |
| 90 |
git tag -s vX.Y.Z -m "vX.Y.Z" <merge-commit-sha> |
| 91 |
git tag -v vX.Y.Z |
| 92 |
git push origin vX.Y.Z |
| 93 |
``` |
| 94 |
|
| 95 |
The tag message body is the bare string `vX.Y.Z` — no "Release ..." prefix, no prose. Matches the v0.8.0 style. |
| 96 |
|
| 97 |
After pushing, CI's `create_release` job auto-creates a **draft** release with the cross-compiled binaries (`bpftop-aarch64-unknown-linux-gnu`, `bpftop-x86_64-unknown-linux-gnu`) attached. Wait a few seconds, then verify: |
| 98 |
|
| 99 |
```bash |
| 100 |
gh release list --limit 3 |
| 101 |
gh release view vX.Y.Z |
| 102 |
``` |
| 103 |
|
| 104 |
You'll edit this draft in step 5. Don't `gh release create` a second one. |
| 105 |
|
| 106 |
--- |
| 107 |
|
| 108 |
## Step 5: Draft the release notes |
| 109 |
|
| 110 |
The template lives at `assets/release-notes-template.md` and a worked example for v0.9.0 is at `assets/release-notes-example-v0.9.0.md`. Read both before drafting — the example is the single best reference for tone, grouping, and formatting. |
| 111 |
|
| 112 |
The structure, in order: |
| 113 |
|
| 114 |
1. `## What's New` — one short prose paragraph (2-3 sentences) summarizing the headline changes |
| 115 |
2. `### Features` — `feat:` commits, new user-facing functionality |
| 116 |
3. `### Fixes` — `fix:` commits |
| 117 |
4. `### Maintenance` — `chore:`, `refactor:`, `ci:`, dep bumps. Drop internal AI-assistant / Claude-workflow churn — invisible to users, clutters the changelog. |
| 118 |
5. `## New Contributors` — first-timers, one line each |
| 119 |
6. `## Contributors` — alphabetical `Display Name @login`, one per line |
| 120 |
7. Full Changelog link — `https://github.com/jfernandez/bpftop/compare/vPREV...vX.Y.Z` |
| 121 |
|
| 122 |
Each Features/Fixes/Maintenance bullet ends with `(#N)` referencing its PR. No `by @author` inline — attribution lives in the dedicated Contributors section. Direct-to-main commits with no PR don't get a number. |
| 123 |
|
| 124 |
### Resolving the Contributors and New Contributors sections |
| 125 |
|
| 126 |
Run the bundled script. It encodes the project's exclusion and sort rules, and resolves first-timer status correctly via PR history: |
| 127 |
|
| 128 |
```bash |
| 129 |
.claude/skills/cut-release/scripts/contributors.sh vPREV |
| 130 |
``` |
| 131 |
|
| 132 |
Output is two ready-to-paste markdown sections. |
| 133 |
|
| 134 |
The script enforces: |
| 135 |
|
| 136 |
- **First-timer detection via PR history per GitHub login.** Comparing commit author names (`git log --pretty=%an`) misses people whose local `git config user.name` has changed since their first contribution — the same person can appear under different names across years. The login is stable. |
| 137 |
- **Bots excluded.** GitHub reports bots as either `dependabot[bot]` or `app/dependabot`; the script filters both forms. |
| 138 |
- **Maintainer (`jfernandez`) included.** This is a deliberate choice — the user wants their own name in the Contributors list. The convention in some projects is to omit the publisher; bpftop chooses to include them. |
| 139 |
- **Alphabetical by display name, case-insensitive.** |
| 140 |
|
| 141 |
### Apply the notes and link the user |
| 142 |
|
| 143 |
```bash |
| 144 |
gh release edit vX.Y.Z --notes "$(cat <<'EOF' |
| 145 |
...notes... |
| 146 |
EOF |
| 147 |
)" |
| 148 |
``` |
| 149 |
|
| 150 |
Tell the user the URL of the draft and wait for review. Publish only after they confirm: |
| 151 |
|
| 152 |
```bash |
| 153 |
gh release edit vX.Y.Z --draft=false |
| 154 |
``` |
| 155 |
|
| 156 |
--- |
| 157 |
|
| 158 |
## Things that bit us before |
| 159 |
|
| 160 |
- **GitHub shows the GPG key as expired but it isn't locally.** Extending a GPG key's expiration locally doesn't propagate to GitHub, and same-fingerprint re-uploads are silently no-op'd. Fix: delete the existing GPG key on GitHub Settings → SSH and GPG keys, then re-upload `gpg --armor --export <keyid>`. Past commits stay verified once re-uploaded. |
| 161 |
- **Mistakenly flagged a returning contributor as a first-timer.** Always use the bundled `contributors.sh` script — don't eyeball it from `git log`. |
| 162 |
- **Slipped a body into the release commit.** If a body sneaks in, `git commit --amend` and force-push the branch before merging. Subject only + sign-off, empty PR body. |
| 163 |
- **Tagged the local feature-branch tip instead of the merge commit.** Always `git checkout main && git pull --ff-only` before tagging, then tag the merge commit by SHA captured from `gh pr view`. |
| 164 |
- **Created a second draft when CI already auto-created one.** CI creates the draft on tag push. Always `gh release edit vX.Y.Z` to populate it; never `gh release create`. |
| 165 |
|
| 166 |
--- |
| 167 |
|
| 168 |
## Doing only one step |
| 169 |
|
| 170 |
If the user says "just tag it" or "just draft the notes", do only that step. Still confirm version / tag SHA / notes content before any irreversible action (push, publish). |
| 171 |
|
| 172 |
--- |
| 173 |
|
| 174 |
## File layout |
| 175 |
|
| 176 |
``` |
| 177 |
.claude/skills/cut-release/ |
| 178 |
├── SKILL.md (this file — workflow) |
| 179 |
├── assets/ |
| 180 |
│ ├── release-notes-template.md (literal template with placeholders) |
| 181 |
│ └── release-notes-example-v0.9.0.md (worked example — best reference) |
| 182 |
└── scripts/ |
| 183 |
└── contributors.sh (resolves Contributors + New Contributors) |
| 184 |
``` |