diff --git a/AGENTS.md b/AGENTS.md index dc31a641..80c9f3cb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -138,6 +138,113 @@ Every new CLI option **must** be added in **all** of these locations: - Each protocol (redis/memcached) has its own class hierarchy - Connection state machine is in `shard_connection.cpp` +## Releasing + +### Release-note style + +GitHub release notes are curated, not auto-generated. Follow the pattern established +from 2.2.1 onward: + +```markdown +# What's Changed + +## New Features +- **Short title**: One-sentence description ending with the PR number (#123). + +## Bug Fixes +- **Short title**: Description with `inline code` for flag/identifier names (#124). + +## Packaging & Distribution +- ... + +## Developer Tooling & CI Improvements +- ... + +## Maintenance +- ... + +## New Contributors +- @handle made their first contribution (#125) + +**Full Changelog**: https://github.com/redis/memtier_benchmark/compare/... +``` + +Conventions: +- `# What's Changed` heading, then `##` sections (only the sections that have + content — drop empty ones). +- Section order, when present: New Features → Bug Fixes → Packaging & Distribution + → Developer Tooling & CI Improvements → Build & Configuration Improvements → + Maintenance → AI → New Contributors. +- Bullet form: `- **Bold lead phrase**: Sentence-cased description ending with a + period, with the PR number in parens before the period (#NNN).` +- Use inline backticks for CLI flags, file names, and identifiers. +- Close with the `**Full Changelog**` compare link. +- Do *not* paste the GitHub auto-generated `* by @user in ` style — it + was used up to 2.2.0 but has been replaced by the curated form. + +### Patch releases (cherry-picks to a release branch) + +Patch releases live on a release branch (e.g. `2.3` for the 2.3.x line). The flow: + +1. **List the candidates**: `git log --oneline origin/master ^origin/`. + For each commit, decide whether it belongs in a patch release. Skip duplicates + that were applied independently to the release branch (compare diffs, not just + subjects — see `0cb8e9a` vs `d92b163` in the 2.3.1 history). +2. **Branch from the release branch**: `git switch -c release. origin/`. +3. **Cherry-pick in chronological order** so the release-branch history reads + forward. Resolve conflicts as they arise. +4. **Verify CI workflows fire on the release branch.** Workflow files + (`asan.yml`, `ci.yml`, `code-style.yml`, `tsan.yml`, `ubsan.yml`, + `release-rpm.yml`) historically restricted `pull_request: branches:` to + `[master, main]` only. A PR targeting the release branch will run **zero** + checks until the branch list includes the release branch — extend each + workflow's `branches:` filter as part of the release PR if it is missing. +5. **Run `utils/prepare_release.sh `** as the last commit. See gotchas + below. +6. **Open a single PR base `` ← `release.`.** Don't split + the cherry-picks and the version bump into separate PRs for a patch release; + the atomic shape leaves the release branch self-consistent if the PR is + delayed. +7. **After merge, tag and publish a Release** on the merged release-branch HEAD. + The `release: published` event fires `dockers.yml`, `release-rpm.yml`, and + `release.yml` (APT) automatically. +8. **Mirror any review-driven follow-ups back to master** as a separate PR. + Cursor Bugbot frequently catches latent issues on release-prep PRs (e.g. the + `get_total_latency()` narrowing flagged on the 2.3.1 backport); do not let + those fixes live only on the release branch. + +### `utils/prepare_release.sh` gotchas + +`utils/prepare_release.sh ` bumps `configure.ac`, runs +`autoreconf -ivf && ./configure && make && make rebuild-man`, and commits +`configure.ac + memtier_benchmark.1` as a single `Release ` commit. +Watch out for: + +- **Stale `version.h` corrupts the man page.** The Makefile rule + `version.h: $(SHELL) $(srcdir)/version.sh` has **no dependencies**, so once + `version.h` exists `make` won't re-run `version.sh`. The script then bakes an + outdated git SHA into `memtier_benchmark.1` via `help2man`. **Always + `rm -f version.h` before running the script** so the SHA matches HEAD. +- **No branch sanity check.** The script doesn't verify the current branch. + Confirm `git branch --show-current` matches the intended release branch + before running. +- **No version-string validation.** A typo like `2.3.1.` writes a broken + `AC_INIT` line and the failure only surfaces on the next build. Sanity-check + with `grep AC_INIT configure.ac` after the bump commit lands. +- **No tag is created.** The script commits but doesn't tag. After merge you + still need `git tag ` on the merged release-branch tip, push the tag, + and publish a GitHub Release for the workflows to fire. +- **Untracked-file check is dirty-state-only.** The script blocks on tracked + modifications but ignores untracked files. Editor backups like + `configure.ac~` won't trigger the guard. + +### Release-note generation + +Use `gh release create --generate-notes --draft` as a starting point, +then rewrite the body in the curated style above before publishing. Don't +publish the auto-generated draft as-is — it doesn't match the project's +release-note conventions. + ## Debugging ### Debug Build