Changelog Maintenance

Changelog Maintenance

Use this skill when the deliverable is release history or shipped-change communication, not a broad documentation or launch-campaign bundle.

changelog-maintenance is the documentation-cluster anchor for:

• CHANGELOG.md upkeep
• GitHub / GitLab / docs-site release notes
• migration and deprecation updates tied to a shipped change
• customer-facing “what changed” summaries
• lightweight game patch notes and small update posts

Read these support docs before choosing the mode or boundary:

• references/modes-and-boundaries.md
• references/output-packets-and-channel-handoffs.md
• references/release-note-quality-checklist.md
• references/automation-and-source-of-truth.md

When to use this skill

• A repo needs a durable changelog entry or Unreleased refresh based on shipped work
• A release needs audience-appropriate notes for developers, customers, internal stakeholders, or players
• A breaking change, deprecation, or compatibility shift needs a migration update linked from release history
• Release automation drafted notes, but the output still needs truthful grouping, clearer wording, or better route-outs
• A game update needs concise patch notes without collapsing into marketing copy, deployment runbooks, or full help docs
• The real job is deciding the smallest release-writing packet rather than writing every neighboring document from scratch

When not to use this skill

• The main job is an internal spec, runbook, ADR, rollout plan, or deep migration procedure → technical-writing
• The main job is published API / SDK / webhook / developer-portal content → api-documentation
• The main job is end-user onboarding, tutorials, screenshots, FAQs, or help-center walkthroughs → user-guide-writing
• The main job is deployment execution, environment promotion, rollback mechanics, or release orchestration → deployment-automation
• The main job is launch copy, feature positioning, campaign sequencing, or GTM messaging → marketing-automation
• There is no credible shipped evidence yet → collect proof first instead of inventing release notes from a roadmap or TODO list

Instructions

Step 1: Classify one primary release-writing mode

Normalize the request before drafting.

changelog_mode:
  primary_mode: changelog | release-notes | migration-update | game-patch-notes
  audience: developers | end-users | mixed | players | internal-stakeholders | unknown
  release_scope: patch | minor | major | rolling | unknown
  source_of_truth: release-pr | tagged-release | prs | issues | commits | docs | mixed | unknown
  publishing_surface: changelog-file | github-release | docs-site | in-app-updates | steam-news | mixed | unknown
  automation_context: manual | release-drafter | changesets | release-please | autogenerated-release-notes | mixed | unknown
  output_shape: single-entry | summary-plus-links | migration-brief | patch-note-brief | sync-packet | unknown

Use one mode per run:

• changelog → durable repo history in CHANGELOG.md
• release-notes → audience-facing summary of what changed and why it matters
• migration-update → changed behavior, required actions, deadlines, and compatibility notes
• game-patch-notes → concise player-facing update summary

Step 2: Confirm audience, proof, and route-outs

Answer these before writing: 1. Who reads this first? 2. What action should they take after reading it? 3. Which shipped evidence proves each headline claim? 4. Which deeper artifact should carry the rest?

Quick route-out table:

Step 3: Gather the smallest truthful evidence set

Do not write release history from memory alone. Pull the smallest credible packet first:

• merged release PR, tag, or release entry if it exists
• merged PRs / issues / commits included in the release
• linked migration docs, upgrade notes, or help docs
• breaking changes, removals, deprecations, deadlines, or rollout caveats
• publishing-surface constraints (CHANGELOG.md, GitHub Release, customer update hub, Steam patch-note post)
• automation context, if any

If evidence is incomplete, label assumptions and missing proof explicitly.

Step 4: Choose the smallest useful artifact packet

Use references/output-packets-and-channel-handoffs.md.

Default shapes:

• single-entry → one changelog entry or one release-note block
• summary-plus-links → short release summary plus migration/help/API links
• migration-brief → what changed, who is affected, required action, deadline, link-outs
• patch-note-brief → concise new content / tuning / fixes / known issues packet
• sync-packet → release-note draft plus list of downstream docs or channels that must stay aligned

Do not ship a broad handbook when one release packet and a short sync list will do.

Step 5: Apply mode-specific writing rules

• Changelog: favor grouped notable changes over commit archaeology; keep compare links or version/date framing when the repo uses them.
• Release notes: lead with impact, not internal ticket numbers; keep wording plain and scannable.
• Migration update: foreground required action, affected readers, deadline, and compatibility risk.
• Game patch notes: keep the note lightweight and player-facing; do not smuggle rollout mechanics or campaign copy into it.

Step 6: Keep record, communication, and promotion separate

Guard these boundaries aggressively:

• changelog / release notes summarize what shipped
• migration detail lives in linked migration docs when the procedure is too large for the summary
• tutorials / FAQs live in user-guide-writing
• API and integration detail lives in api-documentation
• rollout / rollback mechanics live in deployment-automation
• campaign-style language lives in marketing-automation

Step 7: Work with automation without surrendering judgment

Use automation as draft input, not the final editor.

• Release Drafter / autogenerated release notes → good for PR grouping and starter bullets
• Changesets → good for package/version intent and monorepo release aggregation
• release-please / semantic-release style flows → good for release PRs, version bumps, and commit-driven summaries

Still decide manually:

• the primary audience
• what counts as notable
• what needs a migration link
• what should become a separate help/API/internal doc

Step 8: Run the trust check before publishing

Use references/release-note-quality-checklist.md.

Verify: 1. Every claim matches shipped or merged evidence. 2. The chosen mode fits the audience and channel. 3. Breaking changes, removals, and deadlines are impossible to miss. 4. Route-outs stay explicit instead of bloating the note. 5. The packet is as small as possible while still truthful.

Step 9: Return a brief or the finished artifact

Preferred brief shape before full drafting:

# Release Writing Brief

## Mode
- Primary mode:
- Why it fits:
- Audience:
- Output shape:

## Evidence used
- Source of truth:
- Supporting docs / links:
- Assumptions / missing proof:

## Planned artifact packet
1. main release artifact
2. downstream sync / linked-doc follow-up

## Writing notes
- Breaking changes / deadlines:
- Route-outs kept out of scope:
- Channel-specific constraints:

If the user already asked for the finished artifact, produce the selected packet directly with the matching structure.

Examples

Example 1: Changelog plus migration link

Input

Update CHANGELOG.md for v2.4.0 from the merged PR list and make the Basic Auth deprecation obvious.

Good output direction

• mode: changelog
• output shape: summary-plus-links
• grouped sections such as Added, Changed, Deprecated, Fixed
• migration link or placeholder instead of embedding the full auth procedure

Example 2: Customer-facing release summary

Input

Turn these shipped product updates into release notes customers will actually read.

Good output direction

• mode: release-notes
• output shape: single-entry or summary-plus-links
• benefit-led headings like What’s new, Improvements, Fixes
• route tutorials or help refreshes to user-guide-writing

Example 3: Lightweight game patch notes

Input

Write patch notes for our latest game update and keep them short.

Good output direction

• mode: game-patch-notes
• output shape: patch-note-brief
• concise sections for new content, tuning, fixes, and known issues
• route launch-event hype or campaign beats to marketing-automation

Best practices

1. Start from shipped evidence, not vibes. 2. Pick one primary audience and one primary mode. 3. Use the smallest packet that fits the channel. 4. Separate release summary, migration detail, help docs, API docs, rollout mechanics, and launch messaging. 5. Let automation collect draft material, but do not outsource judgment. 6. Call out breaking changes and deadlines early. 7. Treat patch notes as a real workflow with player-facing constraints, not just a renamed changelog.

References

• Keep a Changelog
• Semantic Versioning 2.0.0
• Release Drafter
• Changesets
• release-please
• GitHub Docs: Automatically generated release notes
• Steamworks: Event Type — Small Update / Patch Notes
• Steamworks: Updating Your Game — Best Practices

Automation and Source of Truth

Source-of-truth priority

When changelog input sources disagree, prefer this order unless the repo clearly documents a different policy:

1. merged release PR / tagged release notes 2. merged PRs included in the release 3. linked issues or milestone notes 4. commit history 5. draft planning docs

Do not treat draft roadmap or TODO items as shipped changes.

Automation lanes

Release Drafter

Good for:

• PR-label grouping
• release-draft generation
• consistent headings

Still requires:

• wording cleanup
• audience fit
• migration / deprecation review
• doc-link hygiene

Changesets

Good for:

• package versioning
• monorepo release notes
• per-package change intent

Still requires:

• deciding what belongs in customer-facing notes
• linking to migration/user guides
• filtering internal-only package noise

release-please

Good for:

• release PRs
• version bumps
• conventional-commit driven summaries

Still requires:

• accurate breaking-change framing
• explicit route-outs for tutorials, API docs, and migrations
• readability review for non-engineer audiences

Practical writing rule

Automation can propose categories and bullets. Humans/agents still decide:

• the primary audience
• what is notable
• what needs a migration link
• what belongs in a separate guide

Game/live-ops note

Steam patch-note workflows favor lightweight title + description style update posts. Do not overload that artifact with build, deployment, or campaign detail.

Changelog / Release-Notes Modes and Boundaries

Core split

changelog-maintenance owns the release-history artifact and the release-summary artifact.

That includes:

• CHANGELOG.md
• GitHub/GitLab release notes
• migration / deprecation summaries attached to a release
• customer-facing “what shipped” notes
• lightweight game patch notes

It does not own every neighboring document.

Route-outs

Mode chooser

1. changelog

Use when the durable source is CHANGELOG.md or an equivalent release-history file.

Best for:

• repo history
• compare links
• grouped notable changes
• long-term historical lookup

2. release-notes

Use when the artifact is meant to be read by developers, admins, or end users after a release.

Best for:

• “what’s new” pages
• in-app update notes
• GitHub Release text
• customer-facing update posts with doc links

3. migration-update

Use when compatibility changed and readers need explicit next steps.

Best for:

• deprecation announcements
• API or behavior changes
• renamed config keys, removed endpoints, changed defaults
• upgrade windows and deadlines

4. game-patch-notes

Use when the update is lightweight and player-facing.

Best for:

• Steam patch notes
• live-ops update summaries
• balance changes and fixes
• concise update notes attached to a shipped build

Common failure modes

• Treating a changelog like a commit archive
• Treating release notes like launch copy
• Hiding breaking changes in a generic “Changed” bullet
• Mixing patch notes, tutorials, and rollout instructions into one blob
• Writing every artifact for “everyone” instead of one primary audience

Output Packets and Channel Handoffs

Use this reference when the front door already knows the work belongs in changelog-maintenance but you still need the smallest truthful release-writing artifact.

Packet chooser

Packet skeletons

1. single-entry

Use for a changelog entry or one concise release-note block.

## [version-or-date]
### Added / Changed / Deprecated / Removed / Fixed / Security
- grouped notable changes

Good when:

• the repo already has the surrounding changelog structure
• deeper docs already exist
• one durable record matters more than audience-specific packaging

2. summary-plus-links

Use for customer/dev/internal release notes that should stay short.

# Release Notes: <version>

## What's new
## Improvements
## Fixes
## Important changes
## Learn more
- migration / help / API links

Good when:

• the audience needs impact-first wording
• the release still points to migration/help/API docs
• the request risks turning into a giant mixed-purpose document

3. migration-brief

Use when the summary alone is unsafe.

# Migration Update: <change>

## What changed
## Who is affected
## Required action
## Deadline / support window
## Links to deeper docs

Good when:

• a breaking change or deprecation needs a visible action
• the timeline matters
• the full procedure belongs in technical-writing or api-documentation

4. patch-note-brief

Use for lightweight game or live-ops updates.

# Patch Notes - <version/date>

## New content / features
## Balance / tuning
## Fixes
## Known issues / next steps

Good when:

• the note is player-facing
• the platform surface rewards concise updates
• build / deployment / campaign detail should stay elsewhere

5. sync-packet

Use when one release update has to keep several other artifacts honest.

# Release Writing Sync Packet

## Primary artifact
- changelog / release-note / patch-note block

## Must-sync follow-ups
- migration doc
- API doc page
- help-center article
- customer update hub entry
- store / news post

Good when:

• the release spans docs, customer comms, and channel-specific notes
• one summary should drive several smaller downstream updates
• you need a bounded handoff instead of writing every artifact immediately

Channel handoff rules

Common packet mistakes

• Writing one blob that tries to be changelog, migration guide, tutorial, and launch post all at once
• Treating autogenerated notes as publish-ready when they still need audience cleanup
• Hiding required action inside a generic Changed bullet
• Sending player patch notes full of rollout or build-process detail
• Forgetting the downstream sync list when one release changed multiple docs surfaces

Release Note Quality Checklist

Use this checklist before finalizing changelog or release-note output.

Accuracy

• Every claim matches shipped or merged evidence
• Version number / release scope is correct
• Breaking changes, removals, or deprecations are explicit
• Migration links point to real docs

Readability

• No raw ticket dumps or commit-log phrasing
• Audience-facing notes use plain language
• Entries are short and scannable
• Sections are grouped logically

Boundary discipline

• Deep technical explanation moved to technical-writing or api-documentation
• Tutorials / FAQs moved to user-guide-writing
• Rollout mechanics moved to deployment-automation
• Campaign-style copy moved to marketing-automation

Trust

• No claims about GA / rollout completeness without proof
• No “various improvements” filler if specifics are available
• Known limitations or next steps are called out when material

Good section labels

• Added
• Changed
• Deprecated
• Removed
• Fixed
• Security
• What’s new
• Improvements
• Breaking changes
• Known issues

Smells that need rewriting

• “Misc updates”
• “Bug fixes and improvements” with no specifics
• internal ticket IDs as the first thing the reader sees
• more than one audience being served equally badly in the same artifact
• migration steps hidden inside a long prose paragraph