Writing API Changelog Entries
Practice writing clear API changelog entries that inform developers about breaking changes, deprecations, and new features.
API changelog conventions
- Breaking change: label first, then exact before/after, failure mode, action required
- Deprecation: "Deprecated in vX, will be removed in vY (date): [thing]. Use [replacement]."
- Migration sections: exact version range in heading + scope + audience qualifier
- Labels: "Action required:" vs. "No action required:" — scannable triage markers
- Structure: version + ISO date → Added / Changed / Fixed / Deprecated / Removed
Question 0 of 5
Which sentence best announces a breaking change in an API changelog?
Breaking change announcements must label the change, name the exact before/after behaviour, state the failure mode, and give the action required.
- "Breaking change:" label — developers scan changelogs for this label to decide whether an upgrade is safe. It must appear at the start.
- Exact before/after —
Token YOUR_KEY→Bearer YOUR_KEY. The developer must be able to search their codebase for the old string. - Failure mode —
401 Unauthorized. Developers need to know how the breakage manifests so they can test before deploying. - Call to action — "Update your headers before upgrading to v3." Specific and imperative.
Which sentence correctly documents a deprecation notice in an API changelog?
A deprecation notice must state the version deprecated in, the removal version (with a timeline), the exact endpoint/feature being deprecated, the replacement, and where to find migration help.
- "Deprecated in v2.0, will be removed in v3.0 (Q4 2026)" — gives developers a concrete timeline to plan their migration. "Soon" is not a timeline.
- Exact old path —
GET /v1/users/search— developers can search their codebase. - Exact replacement —
GET /v2/users?q=— removes guesswork. - Migration guide link — deprecation without a migration path is an incomplete notice.
Which heading and opening sentence best starts a "Migrating from v1 to v2" section?
A migration section heading must name the exact versions, and the opening sentence must scope what the guide covers and who needs to act.
- Exact versions in heading — "Migrating from v1 to v2" is scannable. Developers on v1.5 upgrading to v2 know immediately this guide is for them.
- Scope statement — "covers the breaking changes introduced in v2 and the steps required to update your integration" — tells the reader what they will get from the section.
- Audience qualifier — "If you are already on v2, no action is needed" — saves time for readers who do not need to act. This is a professional courtesy in technical writing.
Which phrasing correctly distinguishes between "No action required" and "Action required" in a changelog entry?
"Action required" and "No action required" are the standard markers that let developers instantly classify a changelog entry as urgent or passive.
- "Action required" — precedes any change that will break or alter behaviour in existing integrations. The sentence that follows must state the exact action: "update your X to Y".
- "No action required" — precedes additive, performance, or internal changes. The sentence should explain the benefit: "response times improved by 40%" and reassure: "fully transparent to existing integrations".
Which changelog entry follows the correct versioned structure for a new feature release?
A versioned changelog entry follows the Keep a Changelog convention: version + date header, then sections for Added / Changed / Fixed / Deprecated / Removed / Security.
- Version + ISO date —
v2.4.0 — 2026-03-15. The date matters for auditing when a behaviour changed. - Added section — new capabilities, additive only.
- Changed section — modified behaviour; must state old vs. new behaviour and action required status.
- Fixed section — bug fixes; useful for developers who were working around the bug.