From 3f09c683cc440b308c17db5a8f9c89ce4449df6c Mon Sep 17 00:00:00 2001
From: Jeremiah Lowin <153965+jlowin@users.noreply.github.com>
Date: Wed, 3 Jun 2026 10:14:28 -0400
Subject: [PATCH] Document --notes-start-tag requirement in release
 instructions (#4275)

---
 CLAUDE.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 2bc9d6cd2..3d9cb95a8 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -84,9 +84,11 @@ Only cut releases when the maintainer explicitly asks. Tags follow `v<version>`
 Write the maintainer-approved handwritten notes to a temporary file, then create the release. `--generate-notes` appends the auto-generated changelog after the handwritten content.
 
 ```bash
-gh release create v3.2.0 --target main --title "v3.2.0: Theme Here" --generate-notes --notes-file /tmp/release-notes.md
+gh release create v3.2.0 --target main --title "v3.2.0: Theme Here" --generate-notes --notes-start-tag v3.1.1 --notes-file /tmp/release-notes.md
 ```
 
+**Always pass `--notes-start-tag <last-stable-tag>`.** Without it, `--generate-notes` picks the most recent prior tag as the changelog start point — and if a prerelease exists (e.g. `v3.4.0b1`), it starts from *that*, silently truncating the PR list to only the commits since the beta. Pin it to the last stable release (e.g. `v3.3.1` when cutting `v3.4.0`). Verify after: the compare link at the bottom of the generated notes should read `v<last-stable>...v<new>`.
+
 Most releases target `main`, but maintenance or backport releases may target a different branch (e.g., `release/2.x`). Confirm the target with the maintainer if there's any ambiguity.
 
 The handwritten notes are prepended above the auto-generated changelog and are the part that matters. Do not include a title in the notes body — the release title (`v{version}: {pun}`) already serves as the heading. Work with the maintainer to draft the notes — propose a draft, get feedback, iterate. Do not publish without the maintainer's sign-off.