Changelog Writing

Changelog entries should describe user-observable behavior, not internal implementation details.

Translation layers:
• "NullPointerException" → "crash" or "error"
• "UserService" → doesn't matter to users
• "empty payloads" → "all fields left blank"

The user-facing rewrite tells users:
1. What type of entry this is ("Fixed")
2. What happened from their perspective ("app crashed")
3. When it happened ("when submitting a form with all fields blank")

Option B is close but slightly more verbose ("submitting a form with no required fields filled in" = more words than needed).
Option C ✓ — same information, tighter language.

Key vocabulary:
• User-observable behavior — what the user sees or experiences, not internal system state
• Changelog entry types — Added, Fixed, Changed, Deprecated, Removed, Security
• Technical-to-plain translation — converting internal error names to user-facing descriptions
• Keep a Changelog — the widely adopted changelog format standard (keepachangelog.com)

Feature changelog entries need: what you can do now + key capabilities + documentation link.

"Added support for webhooks" tells developers nothing they can act on:
• Which events trigger webhooks?
• What payload format?
• How do I set one up?

Better: "Added: Webhooks — get real-time notifications when orders complete, payments fail, or subscriptions change. Configure endpoints in Settings → Webhooks. See the webhooks guide →"

This tells developers:
1. What the feature is
2. Specific events available (order complete, payment fail, subscription change)
3. Where to configure it (Settings → Webhooks)
4. Where to learn more (documentation link)

Key vocabulary:
• Feature entry — an "Added" entry describing new functionality
• User benefit description — explaining what users can now accomplish, not just what was built
• Capability enumeration — listing specific sub-features or use cases within a larger feature
• Documentation link — a reference to the full docs for readers who want more depth

Breaking changes require maximum visibility: visual warning, clear deadline, and a migration guide link.

Elements required for breaking change entries:
1. Visual signal — ⚠️ or "BREAKING CHANGE" prominently at the start
2. What changed — old behavior → new behavior
3. Hard deadline — exact date old behavior stops working
4. Migration guide link — how to update without breaking

Option B is good but lacks the visual warning signal (⚠️) and the migration guide link.
Option D ("security improvement") is actively dangerous — it obscures a breaking change behind positive framing.

Why the migration link is non-negotiable:
• Teams need to plan the migration
• Without the guide, they'll flood support with the same question
• It's the single most important thing developers need in this moment

Key vocabulary:
• Breaking change — a modification that requires existing users to update their code
• Deprecation — announcing that a feature will be removed in a future version
• Migration guide — documentation explaining how to update code to work with the new version
• Sunset date — the specific date when deprecated functionality will be removed

Changelogs need categorical structure so developers can quickly find the type of change relevant to them.

Why categorization matters:
• A security team scanning the changelog only cares about "Security" entries
• A developer asked "did anything break in this release?" needs "Breaking Changes" or "Changed"
• A sales engineer demoing new features needs the "Added" section

Standard categories (Keep a Changelog format):
• Added — new features
• Changed — changes to existing functionality
• Deprecated — features that will be removed
• Removed — features that were removed
• Fixed — bug fixes
• Security — security patches

Option D is wrong — individual blog posts for every change is impractical and creates noise; most changes belong in the changelog.

Key vocabulary:
• Categorical changelog — a changelog organized by type of change (Added, Fixed, etc.)
• Keep a Changelog — the widely adopted format standard for developer changelogs
• Scanning behavior — the way developers read changelogs by type, not linearly
• Release notes — a more narrative version of a changelog, often published on a blog

The best changelog practice is to update it at PR time — when the change is live in the developer's mind.

Why "when we have time" fails:
• Developers forget what changed between releases
• Changelogs written post-hoc become incomplete
• Users lose trust when the changelog is clearly incomplete or out of date

Why automatic git-commit changelogs (Option B) fail:
• Commit messages are written for developers ("Fix edge case in checkout flow") not users ("Fixed: checkout sometimes skipped payment step")
• Auto-generated changelogs expose internal code language to end users
• They don't distinguish significance (a typo fix and a breaking change look the same)

The CHANGELOG.md-in-repo approach:
• Lives with the code — never lost
• Updated at PR time (while context is fresh)
• Reviewed as part of the PR process
• Can be rendered by GitHub as a formatted release note

Key vocabulary:
• CHANGELOG.md — a markdown file in the repository root tracking all notable changes
• PR-time changelog update — the practice of updating the changelog as part of submitting a pull request
• Release notes — a formatted, audience-friendly version of the changelog for a specific release
• Auto-generated changelog — a changelog created from commit messages (often insufficient for end users)