Skip to content
Writing Style Library

Changelog Entry

A structured release entry naming what was added, changed, fixed, or removed in a given version - grouped by impact class under a version heading.

Changelog Entry

Section titled “Changelog Entry”

A changelog entry is the structured short form of a release announcement. It lives under a version heading and groups items by impact class (Added, Changed, Fixed, Deprecated, Removed, Security). The grouping itself is the load-bearing convention: it lets a reader answer “did anything break for me” and “did anything I wanted get fixed” in seconds.

Canonical template

Section titled “Canonical template”
## [Version] - YYYY-MM-DD


### Added
- [New feature, described from the user's perspective] (#PR)


### Changed
- [Behavior change that does not break existing usage] (#PR)


### Deprecated
- [Feature scheduled for removal in a future version, with migration note] (#PR)


### Removed
- [Feature deleted in this version, with migration note] (#PR)


### Fixed
- [Bug fix, described from the user's perspective] (#PR)


### Security
- [Security fix, often with CVE link or advisory link] (#PR)

When to use

Section titled “When to use”

Use a changelog entry for software release notes, version migration docs, and library upgrade guides where users need to scan impact quickly. Each version gets one entry; entries accumulate in a single CHANGELOG.md with newest at the top.

When not to use

Section titled “When not to use”

Do not use this format for marketing-style release announcements (write a long-form blog post instead). Do not use it for internal team status updates. Do not paste a git log and call it a changelog - the grouping by impact class is the whole point.

Pairs well with

Section titled “Pairs well with”

technical-writer, matter-of-fact, decision-log

Often confused with

Section titled “Often confused with”

meeting-notes: Meeting notes capture discussion that happened in a meeting; they are organized by topic and time. A changelog entry captures what changed in a software release; it is organized by impact class. The two share a “structured short form” feel but serve completely different purposes.

Tells

Section titled “Tells”
  • A version heading in the form ”## [Version] - YYYY-MM-DD”
  • Items grouped by impact class: Added, Changed, Deprecated, Removed, Fixed, Security
  • Each item is one line, past tense or a short noun phrase
  • Items written from the user’s perspective and linked to the underlying PR or issue
  • Newest version at the top, with empty subsections omitted
  • Breaking changes called out explicitly with a migration note

Anti-patterns

Section titled “Anti-patterns”
  • Pasting a flat list of raw commit messages under the version heading - Without grouping by impact class it has stopped being a changelog and become a git log; the grouping is the whole load-bearing convention.
  • Writing items from the developer’s internal perspective rather than the user’s - A reader scans a changelog to learn what changed for them; “refactored the auth module” answers a question no user asked.
  • Adding marketing language or narrative framing to the entries - That is a release-announcement blog post, not a changelog; the format is a matter-of-fact scan surface, not a place to sell the release.

Failure modes

Section titled “Failure modes”
  • Swells each line into an essay - a one-line entry grows into a paragraph of rationale, caveats, and backstory - Keep each item to a single scannable line; if an entry needs a paragraph to explain, link out to the PR or a migration guide and leave one line behind.
  • Multiplies impact-class sections beyond the standard set until the scan structure itself becomes noise - Stick to the established subsections; a reader relies on a known, small set of impact classes, so resist inventing per-release categories.

Instruction

Section titled “Instruction”
Write a changelog entry for a software release. Use a version heading in the form
"## [VERSION] - YYYY-MM-DD". Group items under the six standard subsections: Added, Changed,
Deprecated, Removed, Fixed, Security. Omit empty subsections. Each item should be one line,
written from the user's perspective (what changed for them), and linked to the underlying PR or
issue where possible. Use matter-of-fact tone. Do not editorialize, do not market, do not narrate.
If an item is a breaking change, say so explicitly and include a migration note.

Template

Section titled “Template”

See the Changelog Entry template.

Section titled “Related”

Pairs well with

Section titled “Pairs well with”

Technical Writer, Matter of Fact, Decision Log

Avoid with

Section titled “Avoid with”

Storyteller, Narrative Case Study

Often confused with

Section titled “Often confused with”

Meeting Notes

Examples

Section titled “Examples”

Team Standup Process - Changelog

Section titled “Team Standup Process - Changelog”

All notable changes to this team’s standup ritual are documented here. Versioning loosely follows SemVer: breaking ritual changes bump the major version.

[2.0.0] - Async-first trial

Section titled “[2.0.0] - Async-first trial”

Major change to how the 11-person team running across 4 timezones runs standups. This release ends the daily sync standup and replaces it with a written async post plus a single weekly working session. A 30-day trial period begins with this release.

Added

Section titled “Added”
  • Async standup post in #team-standup, due by 10am local time, using a fixed three-field template (Shipped / In progress / Blocked or at risk).
  • Slack shortcut /standup that pre-fills the three-field template.
  • Thursday working session, 60 minutes, 8am Pacific / 8:30pm IST. Cancellable by Wednesday 5pm Pacific if there is no agenda.
  • On-call engineer is now responsible for triaging @mention blockers in #team-standup within the workday. New on-call section added to the playbook.
  • Trial retro doc at docs/trial-retro.md for capturing mid-trial feedback in one place.

Changed

Section titled “Changed”
  • On-call engineer’s morning responsibility shifts from running the sync standup to scanning the async channel once between 10am and 11am Pacific.
  • “Blocked” became “Blocked or at risk.” We were under-reporting because nothing felt fully blocked until it was too late.
  • Engineering manager’s role on Mondays moves from facilitator to async reader. Office hours added Tuesday afternoon for 1:1 follow-ups.

Deprecated

Section titled “Deprecated”
  • “Quick sync after standup” sidebars. If something needs a 1:1, schedule it; do not assume the standup hangover provides one.

Removed

Section titled “Removed”
  • Daily 9am Pacific sync standup. The recurring calendar invite has been deleted from all 11 calendars.
  • Manual standup notes doc. Async posts in Slack are now the source of truth and are searchable via channel history.
  • Round-robin status order. There is no order in async; people post when they start their day.

Migration notes

Section titled “Migration notes”
  • Engineers in IST: you get your evenings back. The 9:30pm slot is yours again.
  • Engineers in US Pacific and Eastern: your first 30 minutes of the day are now writing instead of talking.
  • If you forget to post by 10am local, the on-call will @mention you. Two missed posts in a week triggers a check-in, not a punishment.

[1.4.2] - Previous release

Section titled “[1.4.2] - Previous release”
  • Fixed: timezone display in the standup notes doc was showing PST year-round during daylight saving.

[1.0.0] - Initial sync standup process

Section titled “[1.0.0] - Initial sync standup process”
  • Daily 9am Pacific standup, 15-minute time box, round-robin order, notes captured in a shared doc.

Appears in diff-pairs

Section titled “Appears in diff-pairs”