Skip to content

Commit 68f1f14

Browse files
leggetterclaude
andcommitted
docs(release): keep release notes out of the repo
The GitHub Release is the record — CHANGELOG.md has said so for years. A committed copy drifts the moment anyone edits the Release, and a plans/ directory filling with dead notes serves nobody. v3.0.0-release-notes.md is untracked rather than deleted: it stays on disk to draft in and paste from, and plans/*-release-notes.md is gitignored so the next one does not need this decision made again. The rule is in the voice guide, not just in .gitignore, because that is where someone drafting will be looking. Also tightened the voice guide against its own rules. The section on cutting to length opened with sixty words of what went wrong in this release before reaching the rule — the same self-narrating register the guide tells you to avoid. Rule first, evidence after. The table ban is now scoped to release notes, since this file uses one and the data is the clearest form for it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
1 parent 3b8b929 commit 68f1f14

4 files changed

Lines changed: 25 additions & 213 deletions

File tree

‎.agents/skills/hookdeck-cli-release/references/release-notes-voice.md‎

Lines changed: 14 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,11 @@ Structure is in [release-notes-template.md](release-notes-template.md). This fil
55
Read [v2.6.0](https://github.com/hookdeck/hookdeck-cli/releases/tag/v2.6.0) in full before
66
drafting. It is the specification; this is the summary.
77

8-
## Length is the rule people get wrong
8+
Draft wherever you like — `plans/*-release-notes.md` is gitignored for this — but **do not commit
9+
the notes.** The GitHub Release is the record. A copy in the repo drifts the moment anyone edits
10+
the Release, and `CHANGELOG.md` already points at Releases for exactly this reason.
11+
12+
## Length
913

1014
Measured across the last three GA releases:
1115

@@ -22,8 +26,7 @@ release note — cut it, do not justify it.
2226
A bullet is **two to three sentences**: what changed, then the consequence that made it matter. The
2327
longest bullet in any recent release is about 120 words, and that is the ceiling, not the aim.
2428

25-
**Link out for the rest.** The reader who wants the mechanism follows the issue or PR. That is what
26-
the links are for, and it is why an entry does not need to carry the full story.
29+
**Link out for the rest.** The reader who wants the mechanism follows the issue or PR.
2730

2831
Re-measure before publishing:
2932

@@ -93,16 +96,15 @@ reader recognises — give the new name after it:
9396
Getting this backwards sends someone looking for a tool they have never had, in a bug report about
9497
software they have been running for weeks.
9598

96-
## Cutting to length: what is safe to remove
99+
## Cutting to length
97100

98-
Length is a real constraint, but three separate errors in the v3.0.0 draft came from a compression
99-
pass, not from the first draft: the detail that three tools keep the `hookdeck_` prefix (which made
100-
the rename claim false), the name of the `--allow-write` flag on the Outpost server, and the worked
101-
example under "and the next command disagreed", which left the phrase meaningless.
101+
**Cut padding. Never cut a qualification, or the example a claim rests on.** Where the word target
102+
and accuracy conflict, accuracy wins and the entry is long.
102103

103-
**Cut padding. Never cut a qualification, or the example a claim rests on.** If an entry cannot
104-
reach the word target without losing one of those, it is a long entry — take the words. Length is
105-
the default, accuracy is the constraint.
104+
Compressing the v3.0.0 draft broke three things, each a qualification that looked like padding: the
105+
three tools that keep the `hookdeck_` prefix (losing it made the rename claim false), the name of
106+
the `--allow-write` flag, and the example under "and the next command disagreed", without which the
107+
phrase means nothing.
106108

107109
## What this voice avoids
108110

@@ -113,5 +115,5 @@ the default, accuracy is the constraint.
113115
- **Bare negatives.** "Nothing was removed" gives the reader nothing to do. v2.5.0 turns the same
114116
thought into: "Nothing was removed or renamed, but if you have automation that depended on the
115117
old behaviour, these are the ones to check."
116-
- **Tables.** No recent release uses one.
118+
- **Tables in a release note.** No recent release uses one. (This file is not a release note.)
117119
- **Restating the commit.** The reader does not care which function moved.

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,3 +25,7 @@ test-scripts/.install-test/
2525
# Claude Code temporary worktrees
2626
.claude/worktrees/
2727
.worktrees/
28+
29+
# Release notes are drafted here and pasted into the GitHub Release.
30+
# The Release is the record; a committed copy only drifts from it.
31+
plans/*-release-notes.md

‎plans/mcp_read_write_tool_split.md‎

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -700,14 +700,13 @@ version the committed document does not — would close that.
700700

701701
## Release notes for v3.0.0
702702

703-
Lifted out to [`v3.0.0-release-notes.md`](./v3.0.0-release-notes.md), which is the copy to paste
704-
into the GitHub Release. They were the one part of this document with a life after the release,
705-
and they were hard to find at the bottom of a planning doc.
706-
707-
Rewritten there in the voice the last several releases use — see
708-
`.agents/skills/hookdeck-cli-release/references/release-notes-voice.md`. The draft that lived here
709-
was written like a plan: a table categorising readers, and a note about what had *not* changed.
710-
Neither belongs in a release note.
703+
Published on the [GitHub Release](https://github.com/hookdeck/hookdeck-cli/releases/tag/v3.0.0),
704+
which is the record. They are drafted in `plans/v3.0.0-release-notes.md`, which is gitignored: a
705+
committed copy would only drift from the Release once anyone edited it there.
706+
707+
How to write them is in `.agents/skills/hookdeck-cli-release/references/release-notes-voice.md`.
708+
The draft that lived in this section was written like a plan — a table categorising readers, and a
709+
note about what had *not* changed — which is what prompted that guide.
711710

712711
## Open questions
713712

‎plans/v3.0.0-release-notes.md‎

Lines changed: 0 additions & 193 deletions
This file was deleted.

0 commit comments

Comments
 (0)