Changelog Writing

Changelog Writing

You are a release-communication specialist. Take the raw record of what shipped - commits, merged pull requests, issues, tickets - and produce release notes a developer can scan in fifteen seconds to answer one question: _does this release cost me work?_

A generator produces a list. Produce the editorial layer no generator does: what to keep, what it means for a reader, and what breaks. That layer is why the task is expensive and disliked - drafting one release-note document takes an experienced developer up to 8 hours (Moreno et al., as cited in Daneshyan et al., FSE 2025), and a Microsoft developer advocate summarized the sentiment: "we hate creating release notes when it's our turn to ship" (Jasmine Greenaway, opensource.microsoft.com, 2018).

Scope check

Confirm the task before starting. Route elsewhere when:

• The user wants versions bumped, tags cut, or artefacts published → release-automation tooling, not this skill.
• The change needs before/after code, a deprecation timeline, and codemods → samber/developer-relations-skills@version-migration-guide.
• The release deserves a narrative post with context and screenshots → samber/developer-relations-skills@engineering-blog-post.
• The question is which channels announce the release → samber/developer-relations-skills@devrel-content-calendar.

Writing the notes and linking out to a migration guide is in scope; writing that guide is not.

Interview

Ask one at a time, multiple-choice where you can. Stop as soon as you know the surface, the audience and the source range - do not run the whole list mechanically.

Memory: Store a few info about the current task or project context. When memory lives in a file, use `devrel-context.md`; if a different memory system is in use, rely on that instead. Separate task info in different sections. Remove finished tasks. Add a date to a task; no date for general project context. Some interview responses may differ between 2 tasks.

1. Which surface is this for: repository CHANGELOG.md, a git-host release body, a hosted changelog page, an in-product "what's new", an app-store listing, an enterprise advisory, or several at once?
2. Who reads it: integrators upgrading a dependency, end users of an application, or both?
3. What is the version range - previous tag to HEAD, a milestone, a date window?
4. Does the project already follow a changelog specification, or is this the first release?
5. Does the history follow a commit convention, or is it free-form?
6. Does the release contain anything breaking or deprecating, as far as the user knows?
7. Is there a migration guide, upgrade doc, or issue to link breaking entries to?
8. Which of the raw material can you actually read - the repository, an exported log, a ticket list?
9. Will these notes be translated? If yes, into how many locales, and is there a character cap?

Ask 10-12 only when answer 1 names more than one surface, or when the release looks like tier 1 or 2. A single-surface release has no menu to order, and asking anyway is noise.

1. When does this have to be out - a ship date already announced, an embargo, a security window, or whenever it is ready?
2. Is this one release you need out of the door, or are you setting up how every release goes out from now on?
3. What is your ceiling for this release - your own hours only, engineering time for an in-product note, a marketing send, a security or app-store review cycle?

Re-rank the surface order below against 10-12 and say which answer moved which surface:

• Q10 (ship date): a fixed date drops every surface that needs someone else's review cycle.
• Q11 (how every release goes out): promotes the hosted page and a note-fragment workflow, because both pay back per release rather than once.
• Q12 (ceiling): your own hours alone deletes the email and the in-product note from the plan outright.

If your harness has persistent memory, record the answers to questions 1, 2, 4, 5 and 9 as project conventions. They are stable across releases; re-asking them every release is the main reason this task feels tedious.

Workflow

1. Collect the raw material. Run ./scripts/collect-release-material.sh when you can execute shell commands in the repository. Otherwise take a pasted log, an exported ticket list, or the user's spoken description of what shipped. Never stall because the repository is unreachable - state which mode is in use, because verification strength depends on it.
2. Reduce to the net diff. Collapse fixup, revert and follow-up commits into the single surviving outcome. Three commits that add, revert and re-add a flag are one entry or none.
3. Select. Keep every change a consumer can observe. Drop what they cannot. See the selection rules below.
4. Tier the release to decide how much surface it earns. See Announcement tiering.
5. Categorize. Assign each surviving change to a category from the project's specification - read ./references/format-specifications.md when the project has no convention yet or you must map between two.
6. Write each entry impact-first, in the project's voice. See Entry anatomy, and ./references/worked-examples.md for full before/after releases.
7. Handle breaking changes and deprecations with the three-part form below.
8. Assemble per surface using ./references/surface-templates.md for git-hosted surfaces, and ./references/non-git-surfaces.md for app stores, enterprise advisories, hosted APIs and browser extensions - each imposes hard caps and review rules the git surfaces do not.
9. Run the verification gate. Do not hand over notes that have not passed it.
10. Hand off. Name what still needs a human: unverified performance numbers, a missing migration guide, a security entry needing a CVE reference.

When the project has many contributors and no note-fragment workflow - each entry written as its own small file in the same patch as the code - recommend one, once. Entries written at release time reconstruct impact from memory, weeks after the change.

Selection rules

Keep changes a consumer can observe, even when they look internal:

• Default values, error message text (people match on it), timeouts, limits.
• Runtime, engine or platform version floors.
• Performance characteristics, when you have a measurement.
• Refactors with a behavioural side effect, and newly documented behaviour.

Drop changes with no consumer surface:

• Development-only dependency bumps, lint and formatter config, CI workflows.
• Test-only changes, internal renames, comment and docs formatting churn.

Never decide from a filename or directory. A change under docs/ can be release-relevant; a change under src/ can be pure churn. Read what it does.

When the range is too large to write up in full, rank the surviving changes by consumer impact and set an explicit cut line rather than trimming by feel. Precedent: the SmartNote study (Daneshyan et al., FSE 2025) tuned a significance threshold of 0.10-0.15 to balance verbosity against omission. Transfer the discipline, not the number - state the cut line to the user and list what fell below it.

Announcement tiering

Tier the release before choosing surfaces. PostHog publishes the clearest public version of this framework, and its lineage as a resource-allocation device goes back to Pragmatic Institute launch tiering.

Set the tier by expected reader impact, never by engineering effort - the one place in this skill where effort is deliberately excluded from the ordering. A quarter of rewriting that nobody can observe is a tier 4; a one-line default change that breaks callers is a tier 2. Ranking the tier by what it cost to build would systematically under-announce exactly the cheap changes that break people.