Codify what a release title names, and the order of the sections - #76
Merged
Conversation
Three things about release notes that were either unwritten or written and then not followed. The title names the product finding or fix. A release note is read by someone building on Hookdeck, so the headline is what changed for them or what we learned about the product they use — not the state of our instrument. Two of the three releases so far follow that; v0.3.0 titles itself with our own scenario coverage, which is a fact about the benchmark rather than about Hookdeck. When nothing shipped, the finding is the title. Sections run Shipped, Discovered, Benchmark. What a reader has a stake in first, repairs to our own instrument last. The website does not group by section, so this is the order of the release page — which is where anyone following a link from a blog post arrives. The notes are written with the `hookdeck-voice` skill loaded. They are public, Hookdeck-branded content, and three sets of them were written without it. The classification rule was already here and correct — Discovered is a *product* finding, an open defect in our own instrument goes in neither section — and it was still misapplied while drafting v0.4.0, which put three instrument findings under Discovered. Stating the sections in reading order puts the rule next to the decision rather than four paragraphs below it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MQzUoMAwEBJWpEGVvVzSjK
The convention said to tag the results commit and that the website reads these releases, and never joined the two: the site resolves the most recent release through the releases API to its tag and reads results/ at that ref, so a bare git tag publishes nothing and the page silently keeps the previous snapshot. Records the command, that lightweight tags are what these are, and that v0.3.0 points at the merge commit of its release PR rather than at a publish commit — the same tree, so it works, but not what the paragraph above it asks for. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MQzUoMAwEBJWpEGVvVzSjK
The website's changelog card was reading neither: a map of three tags to hand-written titles and blurbs lived in the component, so the release name and notes were ignored and a fourth release would have rendered with no summary. Fixed in hookdeck/website#789, which takes the title from the release name and the summary from the first paragraph. That makes two things about the notes load-bearing rather than stylistic. The name is the card heading, so it has to be short. The first paragraph is the card body, so it has to read as a lede rather than a scene-setter that needs the rest of the paragraph behind it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MQzUoMAwEBJWpEGVvVzSjK
The three releases carried sentences — 'The CLI no longer works behind your back in a guest project' — while the website rendered hand-written noun phrases over the top of them. Now that the card reads the release name, the two had to agree, and the noun phrase is the right register: a changelog entry is scanned, so the title names what the release is about and the notes carry the argument. v0.1.0 to v0.3.0 renamed to the copy the page was already showing, which makes hookdeck/website#789 a pure refactor for them: same rendering, one source. Written down because the mistake was mine twice in a row — first a title about our own instrument, then one shaped like a headline. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MQzUoMAwEBJWpEGVvVzSjK
Third attempt at this rule in one afternoon, and the first two are recorded as the counter-examples because I made both. An editorial title argues where a changelog entry should be scanned. A bare noun phrase names the area and drops the verb, so 'No-terminal CLI auth' does not say whether that was fixed, documented or merely found — which is the one thing the line is for. v0.1.0 to v0.3.0 retitled again to carry their verbs. v0.2.0's also corrects what it claims: hookdeck ci already worked, the skill never mentioned it, so the change was documentation rather than a CLI fix. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MQzUoMAwEBJWpEGVvVzSjK
The rule contradicted itself within two paragraphs: one named the sentence titles as the editorial failure mode, the next held the same two strings up as the pattern to follow. Both were written today, an hour apart. Replaced with the distinction that actually decides it. A product fix or finding is the headline when there is one. When the release is work on the benchmark, the title says so — promoting a finding to headline a release that fixed nothing sends the reader looking for a fix that is not there, and dressing instrument work as a product change is the same error reversed. Also records that the changelog card is derived from the release rather than configured in the website, which stopped being a hypothetical today. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MQzUoMAwEBJWpEGVvVzSjK
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Three corrections to how release notes get written, all found while drafting v0.4.0.
The title names the product finding or fix. A release note is read by someone building on Hookdeck. Two of the three releases follow that — "The CLI no longer works behind your back in a guest project", "Agents can now authenticate the CLI without a terminal". v0.3.0 does not: "Outpost coverage goes from one scenario to five" titles the release with our own coverage, which is a fact about the benchmark. When nothing shipped, the finding is the title.
Sections run Shipped, Discovered, Benchmark. What a reader has a stake in first; repairs to our instrument last. The website does not group by section, so this is the order of the release page itself — where anyone following a link from a blog post arrives.
Write the notes with the
hookdeck-voiceskill loaded. They are public, Hookdeck-branded content and three sets were written without it.Note on the classification rule
It was already here, and correct:
Discoveredis a product finding, and an open defect in our own instrument goes in neither section. I still misapplied it twice while drafting v0.4.0 — three instrument findings under Discovered, then two open instrument defects moved into Benchmark, which the same paragraph forbids. Putting the sections in reading order sets the rule beside the decision instead of four paragraphs below it.🤖 Generated with Claude Code
https://claude.ai/code/session_01MQzUoMAwEBJWpEGVvVzSjK