Accumulate release notes in a version-less NEXT.md (#58)

[craigmcchesney]

Closes #58

Plan: plan/tickets/58/plan.md.

Adopts the doc/release-notes/NEXT.md convention from osprey-dcs/dp-grpc#156. Release notes now build up during a cycle instead of being written in one sitting at the cut.

Why

• rel-1.16.0's notes were written and tagged on the same day, so the reasoning behind each change had to be reconstructed after the fact.
• The next version isn't decided yet: it could be 1.17.0 or 2.0.0. release.yml looks up doc/release-notes/<tag>.md exactly, so notes saved under a guessed version are stranded, and the tag that does ship fails its notes check.

With NEXT.md, the version is written down in one place: the git mv to rel-<version>.md at the cut.

What's here

• doc/release-notes/NEXT.md (new):
  • dp-grpc's preamble: the draft names no upcoming version and makes no claims about what else the release contains.
  • Sections for everything user-visible since rel-1.16.0: Release body is missing the verification and install instructions (rel-1.16.0) #56 (the release page is the notes file verbatim, and signature verification covers all three files) and Add mypy to CI: fix real type errors and generate typed protobuf stubs #30 (the mypy CI check, plus the two annotation changes).
  • A Cutting the release checklist. It follows dp-grpc's, adds this repo's two tag-bearing steps (the verification section and the Full Changelog line), and ends with running the checker and starting a fresh NEXT.md.
• .dev/tools/check-release-notes.py: in NEXT.md, the four parts that name the tag are errors: a ## Verifying these artifacts heading, a sigstore verify identity command, a --cert-identity, and a **Full Changelog** line. Only the real forms count, because the checklist mentions all four in prose. The self-test checks both directions: the checklist's prose must pass, and each real form must fail. NEXT.md is now part of the default run; it isn't required to exist.
• CLAUDE.md: "Cutting a release" describes the workflow. A ticket with user-visible changes adds its NEXT.md section in the same PR.

release.yml is unchanged: it never reads any file except the one named for the tag, so NEXT.md can't be published.

Verification

• The checker passes on rel-1.16.0.md and NEXT.md.
• It rejects:
  • NEXT.md with a Full Changelog line appended;
  • NEXT.md renamed to rel-1.17.0.md without the checklist done (10 problems, from the missing verification section onward).
• The self-test fails if the command pattern loses its line anchor, since the checklist's prose would then be flagged.
• ruff lint and format are clean, mypy passes on the checker, and the cookbook checker reports OK: 107 snippets.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Bqq8uGF2zNbHW9FU3vfj7Q

[Copilot]

Copilot review overview

🟢 Approval recommended

No unresolved issues were identified.

Review effort: Lite
Findings: None

What changed in this PR

Introduces a version-less NEXT.md workflow for accumulating release notes before a release version is chosen.

Changes:

• Adds the NEXT.md draft and release-cut checklist.
• Extends release-note validation for draft restrictions.
• Documents the workflow and records the implementation plan.

File	Description
plan/​tickets/​58/​plan.md	Documents the design and implementation.
doc/​release-notes/​NEXT.md	Adds the accumulating release-notes draft.
CLAUDE.md	Documents the release workflow.
.dev/​tools/​check-release-notes.py	Validates release notes and draft restrictions.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.