| 1 | # Release Checklist |
| 2 | |
| 3 | A pre-tag checklist that the v0.8.21/v0.8.22 CHANGELOG gap proved we needed. |
| 4 | Step through this in order from a clean worktree on the final release source. |
| 5 | Treat any unchecked box as a release blocker. |
| 6 | |
| 7 | For deeper context on the underlying tools (preflight scripts, npm smoke, |
| 8 | publish-crates), see [`RELEASE_RUNBOOK.md`](RELEASE_RUNBOOK.md). |
| 9 | For larger milestone releases, add any version-specific acceptance matrix to |
| 10 | the release branch before tagging; use it for provider routes, feature gates, |
| 11 | GUI/runtime smoke, remote-workbench decisions, and credit hygiene that the |
| 12 | generic checklist does not enumerate. |
| 13 | |
| 14 | ## 0. Release source is frozen |
| 15 | |
| 16 | - [ ] The live milestone and PR queue no longer contain work intended for this |
| 17 | version: |
| 18 | ``` |
| 19 | gh issue list --repo Hmbown/CodeWhale --milestone "vX.Y.Z" --state open |
| 20 | gh pr list --repo Hmbown/CodeWhale --state open --limit 100 |
| 21 | ``` |
| 22 | - [ ] Any remaining same-theme work is explicitly retargeted to a later |
| 23 | version or called out as a known issue. Do not bump/tag while still |
| 24 | planning to merge more same-version fixes. |
| 25 | - [ ] The release tag does not already point at an older source SHA, or the |
| 26 | maintainer has deliberately chosen to publish exactly that older SHA: |
| 27 | ``` |
| 28 | git ls-remote origin refs/heads/main refs/tags/vX.Y.Z |
| 29 | gh release view vX.Y.Z --repo Hmbown/CodeWhale |
| 30 | ./scripts/release/check-published.sh X.Y.Z |
| 31 | ``` |
| 32 | - [ ] If `vX.Y.Z` exists with no GitHub Release/packages and `main` has moved |
| 33 | on, stop. Choose one of: publish the existing tag as-is, bump the later |
| 34 | work to the next patch version, or explicitly approve deleting/recreating |
| 35 | the unpublished tag. Do not silently move tags during PR cleanup. |
| 36 | |
| 37 | ## 1. CHANGELOG entry exists for the version |
| 38 | |
| 39 | - [ ] `CHANGELOG.md` has a `## [X.Y.Z] - YYYY-MM-DD` heading at the top |
| 40 | - [ ] The entry credits every external contributor, harvested PR author, |
| 41 | linked issue reporter, reproduction/log provider, reviewer, and |
| 42 | verification helper whose work materially shaped this version. Get the |
| 43 | commit list with: |
| 44 | ``` |
| 45 | git log vPREV..HEAD --no-merges --format="%h %an <%ae> %s" \ |
| 46 | | grep -v '<your-email@…>' |
| 47 | ``` |
| 48 | For each contributor, link both their display name and (when known) |
| 49 | `@github-handle`. Then inspect linked issues and harvested PRs so |
| 50 | reporters/helpers are not lost just because they did not author commits. |
| 51 | - [ ] The entry uses the Keep a Changelog headers — `Added`, `Changed`, |
| 52 | `Fixed`, `Security`, `Removed`, `Deprecated`. Add `Known issues` only |
| 53 | if there is something material the user must work around. |
| 54 | - [ ] The entry mentions all referenced issue/PR numbers as `#NNNN` so the |
| 55 | auto-linker on GitHub picks them up. |
| 56 | - [ ] Run `scripts/sync-changelog.sh` to regenerate `crates/tui/CHANGELOG.md` |
| 57 | (the recent-releases slice embedded in the binary for `/change`). Do |
| 58 | not edit that file by hand, and do not copy the full root changelog |
| 59 | into it — older entries live in `docs/CHANGELOG_ARCHIVE.md`. |
| 60 | - [ ] Run `scripts/release/check-feature-release-notes.sh vPREV HEAD`. Every |
| 61 | issue-linked `feat` commit must leave a receipt in `CHANGELOG.md` or the |
| 62 | archive; the Version drift CI gate runs the same check with full history. |
| 63 | |
| 64 | ## 2. Version pins are in sync |
| 65 | |
| 66 | - [ ] Run `./scripts/release/prepare-release.sh X.Y.Z` — it bumps the |
| 67 | workspace version, every per-crate dependency pin, the npm wrapper |
| 68 | (`version` + `codewhaleBinaryVersion`), Runtime SDK, VS Code extension |
| 69 | and lock, remote-smoke default, public source-candidate facts, and README |
| 70 | install-tag examples; it refreshes the Cargo/npm locks, regenerates |
| 71 | `crates/tui/CHANGELOG.md` and `web/lib/facts.generated.ts`, and ends |
| 72 | by running the version and OHOS gates. Write the CHANGELOG entry |
| 73 | **before** running it. The helper is safe to rerun at the requested |
| 74 | workspace version; it skips replacements but refreshes both generated |
| 75 | files and reruns the gates. |
| 76 | - [ ] `npm/deepseek-tui/package.json` remains private/compatibility-only and |
| 77 | is **not** bumped or published. |
| 78 | - [ ] `./scripts/release/check-versions.sh` reports |
| 79 | `Version state OK: workspace=X.Y.Z, npm=X.Y.Z, npm-binary=X.Y.Z, lockfile in sync.` |
| 80 | - [ ] `./scripts/release/check-ohos-deps.sh` reports that the OpenHarmony |
| 81 | Windows linker keeps the target/sysroot flags, the target enables the |
| 82 | `rquickjs-sys` bindgen edge, and its graph does not pull the unsupported |
| 83 | `nix` 0.28/0.29, `portable-pty`, `starlark`, `arboard`, or `keyring` |
| 84 | crates. |
| 85 | |
| 86 | ## 3. Preflight gates |
| 87 | |
| 88 | Run, in order, from the repo root: |
| 89 | |
| 90 | - [ ] `cargo fmt --all -- --check` |
| 91 | - [ ] `cargo check --workspace --all-targets --locked` |
| 92 | - [ ] `cargo clippy --workspace --all-targets --all-features --locked -- -D warnings` |
| 93 | - [ ] `cargo test --workspace --all-features --locked` |
| 94 | (Re-run any single failure in isolation with |
| 95 | `cargo test -p PKG --bin BIN -- TEST_NAME` before declaring it a flake. |
| 96 | Tests that mutate process-wide state — `HOME`, `cwd`, `RUST_LOG` — |
| 97 | can race in parallel. Document confirmed flakes in `Known issues`.) |
| 98 | - [ ] `./scripts/release/publish-crates.sh dry-run` |
| 99 | |
| 100 | ## 4. npm wrapper smoke |
| 101 | |
| 102 | - [ ] `cargo build --release --locked -p codewhale-cli -p codewhale-tui` |
| 103 | - [ ] `node scripts/release/npm-wrapper-smoke.js` |
| 104 | (Set `DEEPSEEK_TUI_KEEP_SMOKE_DIR=1` if you need to inspect the temp |
| 105 | install afterwards.) |
| 106 | |
| 107 | ## 5. Branch and PR |
| 108 | |
| 109 | - [ ] Branch is pushed: `git push -u origin work/vX.Y.Z-...` |
| 110 | - [ ] PR opened with `gh pr create --base main --title "chore(release): prepare vX.Y.Z"` |
| 111 | - [ ] The PR targets `main` and will be merged before any `vX.Y.Z` tag is |
| 112 | pushed. Do not tag a release-only branch; GitHub will not process |
| 113 | `Closes #N` keywords until those commits reach the default branch. |
| 114 | - [ ] PR body includes: |
| 115 | - one-paragraph summary of the release theme |
| 116 | - a punch list of the new commits since the last release |
| 117 | - explicit call-out of any **Security** items so reviewers see them |
| 118 | - the contributor thank-you list |
| 119 | - the `Known issues` block from the CHANGELOG, if any |
| 120 | - [ ] PR title is **neutral** — do not put CVE-style language or specific |
| 121 | attack details in the title. Save those for the GitHub release notes |
| 122 | after the tag is pushed. |
| 123 | |
| 124 | ## 5b. Branch hygiene (post-merge) |
| 125 | |
| 126 | After the release/integration merge lands, make it obvious where the release |
| 127 | tip lives and clean up stale branches **safely**. A working checkout left on a |
| 128 | scratch/renovate branch (even when `HEAD` already matches the tag) creates |
| 129 | release anxiety: contributors cannot tell whether their work merged. |
| 130 | |
| 131 | - [ ] Run the dry-run report first (read-only, deletes nothing): |
| 132 | |
| 133 | ```sh |
| 134 | ./scripts/release/branch-hygiene.sh --release-branch codex/vX.Y.Z |
| 135 | ``` |
| 136 | |
| 137 | It prints: the current checkout branch, the local + remote release tips, |
| 138 | and the main ref; the branches that are **safe to delete** (tip already |
| 139 | contained in the configured main ref or the release branch); and a |
| 140 | **keep / needs review** list naming each branch, its unique commit count, |
| 141 | the author(s), and the keep reason. The summary line reports how many are |
| 142 | safe-deletes, how many were kept for contributor work, and how many need a |
| 143 | human decision. A diverged local/remote release tip exits non-zero. Use |
| 144 | `--remote upstream` when the canonical release refs live on `upstream` |
| 145 | instead of `origin`. |
| 146 | - [ ] If the working checkout is parked on a stale branch, switch to the |
| 147 | release branch and fast-forward it: |
| 148 | |
| 149 | ```sh |
| 150 | git switch codex/vX.Y.Z |
| 151 | git fetch origin && git merge --ff-only origin/codex/vX.Y.Z # if behind |
| 152 | ``` |
| 153 | - [ ] Only after reviewing the dry-run, delete the **safe** branches. Local |
| 154 | first; add `--prune-remote` to also delete remote safe-deletes: |
| 155 | |
| 156 | ```sh |
| 157 | ./scripts/release/branch-hygiene.sh --release-branch codex/vX.Y.Z --prune --yes |
| 158 | ``` |
| 159 | |
| 160 | The script **never** auto-deletes a branch with unique commits from a |
| 161 | contributor other than Hunter unless that work is already merged. Those |
| 162 | land in the keep/review list with author and reason; review, merge, |
| 163 | harvest with credit, or explicitly preserve them before removing the |
| 164 | branch. When in doubt, leave the branch and record the decision. |
| 165 | |
| 166 | ## 6. CI green and review |
| 167 | |
| 168 | - [ ] All required CI jobs are green. The `versions` job should mirror the |
| 169 | preflight `check-versions.sh` and is your last line of defense. |
| 170 | - [ ] After the final source reaches `main`, dispatch exact-head full CI and the |
| 171 | non-publishing release-candidate build with the same 40-character SHA: |
| 172 | ```bash |
| 173 | candidate_sha="$(git rev-parse origin/main)" |
| 174 | gh workflow run ci.yml --ref main -f expected_sha="${candidate_sha}" |
| 175 | gh workflow run release-candidate.yml --ref main -f expected_sha="${candidate_sha}" |
| 176 | ``` |
| 177 | Both runs must resolve to that SHA. The candidate must report all seven |
| 178 | targets and the complete 34-file asset inventory, including Android |
| 179 | arm64, Windows arm64, `codew`, the NSIS installer, archives, checksum |
| 180 | manifests, and seven compatibility-only `codewhale-tui-*` release |
| 181 | filenames that are not installed commands. These are Actions artifacts |
| 182 | only and are not a release. |
| 183 | - [ ] PR has been reviewed. |
| 184 | |
| 185 | ## 7. Tag and release (after review) |
| 186 | |
| 187 | - [ ] Release PR is merged into `main`, then local `main` is fast-forwarded: |
| 188 | `git switch main && git fetch origin main && git merge --ff-only origin/main` |
| 189 | - [ ] The release source is reachable from `main`: |
| 190 | `./scripts/release/ensure-release-on-main.sh HEAD` |
| 191 | - [ ] Create `vX.Y.Z` from the final `main` SHA using the **Create release tag** |
| 192 | workflow, or create and push a signed local tag: |
| 193 | `git tag -s vX.Y.Z -m "vX.Y.Z" && git push origin vX.Y.Z` |
| 194 | - [ ] The `release.yml` workflow has built and uploaded artifacts to the |
| 195 | GitHub release for this tag. |
| 196 | - [ ] The public GitHub Release assets are proven to match the tag commit |
| 197 | before publishing Cargo or npm: |
| 198 | ``` |
| 199 | ./scripts/release/verify-release-assets.sh X.Y.Z |
| 200 | ``` |
| 201 | This checks the local tag, remote tag, successful Release workflow SHA, |
| 202 | full binary/archive/installer asset set, and both checksum manifests. If |
| 203 | it fails, rerun or repair the GitHub Release workflow before touching any |
| 204 | registry. |
| 205 | - [ ] The live GitHub Release body has its own `## Contributors` or |
| 206 | `## Credits` section; do not rely on "see CHANGELOG" alone. Verify with: |
| 207 | ``` |
| 208 | gh release view vX.Y.Z --repo Hmbown/CodeWhale --json body \ |
| 209 | --jq '.body | test("## (Contributors|Credits)")' |
| 210 | ``` |
| 211 | - [ ] `npm view codewhale@X.Y.Z version codewhaleBinaryVersion --json` |
| 212 | reports the new version on the npm registry. |
| 213 | - [ ] `npm view deepseek-tui deprecated` is non-empty. The legacy npm package |
| 214 | is deprecated and must not receive an `X.Y.Z` publish. |
| 215 | - [ ] Distribution channels are canonical-first: the website install page |
| 216 | (codewhale.net/install) shows Codewhale-native commands first (`npm install -g |
| 217 | codewhale`, `curl .../install.sh | sh`); Homebrew is labeled as legacy |
| 218 | compatibility; the shell installer uses codewhale-native names as documented |
| 219 | in `docs/REBRAND.md#homebrew`. |
| 220 | - [ ] `crates.io` has the new version (or the `publish-crates.sh` job has |
| 221 | pushed it). |
| 222 | - [ ] `ghcr.io/hmbown/codewhale:vX.Y.Z` and `:latest` are updated. |
| 223 | - [ ] The final registry verification passes: |
| 224 | ``` |
| 225 | ./scripts/release/check-published.sh X.Y.Z |
| 226 | ``` |
| 227 | |
| 228 | ## 8. Post-tag |
| 229 | |
| 230 | - [ ] Edit the GitHub release notes to expand any CVE-style or attack |
| 231 | details that were intentionally omitted from the PR title/body. |
| 232 | - [ ] Re-run the GitHub Release body check after any release-workflow rerun; |
| 233 | workflows can overwrite notes and accidentally remove contributor credit. |
| 234 | - [ ] Note any deferred items in the next release's tracking issue. |
| 235 | - [ ] Close any issues that this release fixed. |
| 236 | |
| 237 | --- |
| 238 | |
| 239 | If a step fails, **fix the underlying cause** rather than skipping it. Pre-commit |
| 240 | hooks, signing, and CI are all here to catch real problems. `--no-verify`, |
| 241 | `--no-gpg-sign`, and force-pushing a release branch over reviewers should |
| 242 | remain hard-disabled by convention. |
| 243 |