The changelog field guide: how to announce anything you ship

This is the hundredth guide in this library, and it is deliberately not about a new situation. It is the map of the other ninety-nine.

Release communication looks like one skill — “write down what changed” — but the library got this big because it is really a family of disciplines that only rhyme. The right way to announce a change depends on three questions: what are you shipping, who is on the other end, and where will they read it. A pricing change to enterprise admins over email and a payload change to webhook consumers who can’t pin a version share almost no tactics. This page is the lookup table for those three questions — find your rows, read the two or three guides they point to, and skip the rest.

How to use this page

Nobody should read a hundred guides. If you’re brand new, the guides index has a five-step reading path that covers the fundamentals in order — start there. This page is for the other case: you are shipping something specific this week and want exactly the guides that apply. Scan the four lookup sections below for your situation, your audience, and your channel; most changes match one entry in each. Before that, though, read the next section — it’s the shortest useful summary of the whole library.

Eight rules the whole library keeps rediscovering

Ninety-nine guides about different situations kept arriving at the same small set of conclusions from different directions. If you internalize these, you can improvise everything else:

• 1. Answer the reader’s question, not yours. Every audience has one question — “what’s different for me?” — and it is never answered by your diff, your ticket number, or your internal component names. The whole craft is translation. (How to write a changelog, writing for non-technical users.)
• 2. One canonical home; every channel is a pointer. Announcements fan out — widget, chat, email, social — but exactly one URL is the permanent record, and everything else links to it. Chat is a notification, not an archive. (announcing a feature, Discord & Slack.)
• 3. Never change anything silently. Silent patches, stealth nerfs, quietly removed features, unannounced policy edits — every audience-specific guide independently concludes this is the one trust-bankrupting move. If it changed, it gets an entry. (game patch notes, security fixes.)
• 4. Bad news travels first-class. Breaking changes, removals, price increases, and sunsets get the loudest, plainest, earliest communication — the inverse of the instinct to whisper them. Vagueness reads as cover-up; precision reads as competence. (breaking changes, pricing changes, sunsets.)
• 5. Some events need two documents on two clocks. A ship-time entry that says act now, and a fuller account later — hotfix stub then edit, changelog entry then security advisory, status page then postmortem. Confusing the two clocks produces either panic or silence. (hotfixes, postmortems.)
• 6. Write for the version-skipper. Readers arrive after skipping three releases, from a dependabot diff, or at an update dialog covering six versions. Entries stand alone, carry absolute dates, and show the span they cover. (update dialogs, on-prem operators.)
• 7. Machines move the text; humans make the calls. Automate collection, formatting, and delivery ruthlessly — and never delegate the judgment about what matters and how to say it. Generated output is a draft. (from git commits, AI-generated notes, CI wiring.)
• 8. The unbroken history is the asset. Any single entry is small; years of dated, honest entries are a public record that answers “is this product alive, and do they tell the truth?” — a question buyers, adopters, and auditors all ask. Protect the streak. (what great products get right, archives.)

What are you shipping?

Match the change itself first — the stakes and obligations mostly follow from what kind of change it is:

• A new feature → how to announce a new feature; behind a flag or staged rollout, when do you announce?
• An emergency fix → hotfix communication; if it’s security, advisory vs changelog.
• Something still broken → known issues — admitting it pays.
• A breaking change → announcing breaking changes, backed by a deprecation policy written before you needed it.
• Dropping an OS, browser, or runtime → dropping platform support.
• Killing a product or feature → sunsets and shutdowns.
• A rename, rebrand, or acquisition → announcing an identity change.
• A price change → pricing changes; terms or privacy, policy changes.
• Planned downtime → scheduled maintenance; after an outage, postmortem vs changelog.
• A number that is secretly an interface — rate limits, quotas → rate limit changes.
• A payload you push → webhook and event payload changes; tables other people query → data and schema changelogs.
• The emails your product sends → transactional email changes (new domains read as phishing).
• Unstable, early software → beta and early-access notes.
• Changes that touch assistive tech → accessibility release notes.

Who is on the other end?

The same change reads completely differently depending on who receives it. Four broad families:

Developers who build against you. Their programs, not their eyes, consume your interfaces — so changes must be flagged structurally, not just described. API changelogs and API versioning are the core pair; then it specializes: CLI tools and libraries, one API in seven languages, frameworks an ecosystem must absorb, specs people build against, and design systems. If you’re on the receiving end, vendor changelog monitoring.

People who ship inside someone else’s platform. Store review clocks, host-controlled surfaces, and update mechanics you don’t own: WordPress plugins, browser extensions, themes and templates people copy, integrations that live inside another product, marketplace sellers, and no-code builders without a release pipeline.

Operators who run your software where you can’t reach it. They upgrade on their own schedule, in maintenance windows, sometimes with no rollback: on-prem and self-hosted, firmware, drivers, container images, Terraform modules and Helm charts, network protocols, dbt models and DAGs, an internal developer platform, and the LTS versions you still support.

Gatekeepers, end users, and your own people. Admins who control the rollout — enterprise, corporate IT, schools, government services, regulated industries, payments, plus the auditors reading your changelog as evidence. End users who never asked for the update — customers in plain language, players, and users of AI models they can’t diff. And inward: your own team, the support team who answers for the release, and agency clients.

Where will they read it?

• Your changelog page — the canonical home: layout and UI patterns, whether it helps search rankings, and how long to keep old entries.
• Inside your app → “What’s new” widgets; for stale tabs and version skew, web app update notifications.
• Email → when email is the right channel (and when it isn’t).
• Chat → Discord and Slack without writing a bot.
• Store listings and update dialogs → app store “What’s New” and desktop update dialogs.
• Machines and AI agents → feeds, APIs, and llms.txt.
• Other languages → localizing release notes.

How the writing actually gets done

The workflow guides are about making good notes sustainable: who writes them, on what cadence, drafted from git commits or Jira tickets, wired into CI, assisted by AI where it’s safe, checked by a linter, structured for monorepos, and migrated between tools without losing history. For the words themselves: copy-paste templates, tone and voice, when visuals earn their place, and how far back to backfill. When you ship something big, run the release communication checklist; afterwards, check whether anyone read it.

Versions, formats, and stages

Format questions have shorter answers than they look: what a changelog even is, the Keep a Changelog format, semver in plain English, CalVer vs SemVer, what alpha/beta/RC/GA actually promise, whether a release needs a name, writing updates when there’s no version number at all, CHANGELOG.md vs GitHub Releases, and what to do when the project used to be someone else’s.

The border disputes

Half the confusion in this territory is documents that almost overlap. The rule in every case: they answer different reader questions on different clocks, so keep both and link them. Changelog vs release notes, docs, the product blog, the public roadmap, the status page, and — for game developers — the devlog.

If you only read three

Shipping something this week and out of patience? How to write a changelog for the craft, whichever single guide above matches your audience, and the release communication checklist so nothing gets forgotten on the way out the door.

And if what you’re missing is not advice but a place to put the entries: Wakelog is the free changelog host this library lives on — post from the web, a single curl, or your CI; get a public page, feeds, and a widget. Preview your existing CHANGELOG.md without signing up, or start a changelog in about a minute.

Related guides

• What is a changelog? A plain-English definition (with examples)
  The definition, a real example, how a changelog differs from a commit log, release notes, and a roadmap — and the three-step way to start one.
• How to write a changelog (with examples)
  Structure, tags, cadence, good vs bad entries, and automation — everything you need to keep a changelog people actually read.
• The release communication checklist: everything to update when you ship
  The code being done doesn’t make the release done — a release is finished when the people it affects can find out. What to update before, during, and after you ship, how to scale it to the release, and a copy-paste checklist.

Last updated 2026-08-02 · All guides