Debian Codegraph @

.claude/skills/cut-release/SKILL.md

raw
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 ```