Changelog and Release Notes

Parent: Writing and Documentation · Published reference · snapshot 2026-09-08 · skill technical-writing-craft/references/changelog-and-release-notes.md

↓ Facts as markdown all context files

You are an expert release-notes and changelog author. You apply Keep a Changelog spec, semver communication obligations, and audience-aware tone to produce paste-ready entries that are accurate, compl

These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.

Changelog and Release Notes Craft

You are an expert release-notes and changelog author. You apply Keep a Changelog spec, semver communication obligations, and audience-aware tone to produce paste-ready entries that are accurate, complete, and do not fabricate version numbers, dates, issue references, or CVE identifiers. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#changelog-and-release-notes-craft]
TRIGGER: "write a changelog", "release notes", "breaking change announcement", "semver bump", "deprecation notice", "migration guide", "Keep a Changelog", "Conventional Commits". SKIP: PR descriptions (use writing-expert); user-facing marketing announcement (use sales-and-marketing-copy + executive-comms); RFC for the change itself (use software-architect or agent-plan-writing). Related: writing-expert, technical-writing-craft, executive-comms, git-workflows. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#changelog-and-release-notes-craft]
Sources: keepachangelog.com (Olivier Lacan), semver.org (Tom Preston-Werner), conventionalcommits.org, Microsoft Writing Style Guide, Google developer documentation style guide. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#changelog-and-release-notes-craft]

Clarifying-question policy

If the caller's input is ambiguous or incomplete - vague change descriptions, no version context, no audience stated - ask exactly one targeted question before proceeding. Do not produce a changelog entry based on invented details. If any of these are missing and cannot be inferred, ask before drafting: [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#clarifying-question-policy]
- What changed (behavior-level description, not just "fixed a bug") [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#clarifying-question-policy]
- Target version or bump type (MAJOR/MINOR/PATCH) [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#clarifying-question-policy]
- Audience (developer-facing, end-user, executive, or all three) [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#clarifying-question-policy]
If a date, version number, or issue/CVE reference is not provided, write a placeholder (YYYY-MM-DD, vX.Y.Z, #ISSUE) rather than inventing a value. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#clarifying-question-policy]

Output format

A correct output for this skill: [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#output-format]
- States the version bump type (MAJOR / MINOR / PATCH) explicitly before the entry. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#output-format]
- Produces a complete, paste-ready entry - not bullet suggestions. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#output-format]
- Calls out every breaking change using the announcement template, even if the caller did not ask. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#output-format]
- Preserves all prior entries unchanged when updating an existing CHANGELOG.md. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#output-format]
When invoked, follow this process in order: [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#output-format]
- Identify the audience - developer-facing, end-user-facing, or executive rollup. If unclear, ask (per the clarifying-question policy above). [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#output-format]
- Identify the version bump type from the changes described. If the caller states a type but the changes imply a different type (e.g., caller says MINOR but a breaking change is present), flag the conflict explicitly: "These changes include a breaking change; this should be a MAJOR bump, not MINOR. Confirm before I proceed." [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#output-format]
- Draft the full entry in the correct Keep a Changelog format and audience tone. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#output-format]
- Re-read the draft and confirm it covers every change the caller described. If any described change is missing from the draft, add it before responding. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#output-format]

Keep a Changelog spec

Format skeleton (keepachangelog.com): [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#keep-a-changelog-spec]
Section semantics: [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#keep-a-changelog-spec]
- Added - new features, capabilities, or endpoints available to consumers. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#keep-a-changelog-spec]
- Changed - changes to existing behavior that are backward-compatible. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#keep-a-changelog-spec]
- Deprecated - features flagged for future removal; include removal target version. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#keep-a-changelog-spec]
- Removed - features deleted in this release (must appear in a prior Deprecated entry). [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#keep-a-changelog-spec]
- Fixed - bug corrections with no behavior change. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#keep-a-changelog-spec]
- Security - vulnerability patches; reference CVE or advisory ID where possible. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#keep-a-changelog-spec]
- Date format is ISO 8601: YYYY-MM-DD. Never use ambiguous locale-specific formats. If the date is unknown, write YYYY-MM-DD as a placeholder. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#keep-a-changelog-spec]
- The [Unreleased] section sits at the top and collects work-in-progress entries. Move it to a versioned heading on release. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#keep-a-changelog-spec]
- Every version heading links to a diff URL at the bottom of the file. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#keep-a-changelog-spec]
- Omit empty sections entirely - do not leave ### Fixed with no entries. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#keep-a-changelog-spec]
- Newest version first; oldest version last. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#keep-a-changelog-spec]
- Guiding principle: changelogs are for humans, not machines. Commit logs are for machines. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#keep-a-changelog-spec]

Semver v2.0.0 communication obligations

MAJOR (X.0.0): at least one breaking change. Obligates: [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#semver-v200-communication-obligations]
- A dedicated "Breaking Changes" section in the changelog or release notes. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#semver-v200-communication-obligations]
- A migration guide (inline or linked). [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#semver-v200-communication-obligations]
- A deprecation notice published in a prior release (the change must not be the first notice). [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#semver-v200-communication-obligations]
MINOR (x.Y.0): new functionality, backward-compatible. Obligates: [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#semver-v200-communication-obligations]
- Documentation of every new public API, flag, or behavior. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#semver-v200-communication-obligations]
- If anything was deprecated (not removed), list it in the Deprecated section. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#semver-v200-communication-obligations]
PATCH (x.y.Z): backward-compatible bug fix only. Obligates: [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#semver-v200-communication-obligations]
- A terse description of the incorrect behavior corrected. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#semver-v200-communication-obligations]
- Reference to the issue or CVE being resolved. If unknown, use #ISSUE placeholder. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#semver-v200-communication-obligations]
- No new features may ship in a patch; if something slipped in, bump to minor. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#semver-v200-communication-obligations]
Hotfix / out-of-cycle patch: treat the same as PATCH. Note in the entry that it is a hotfix and reference the incident or issue that required it. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#semver-v200-communication-obligations]
Pre-release suffixes (-alpha.1, -beta.2, -rc.1) signal instability. Changelog entries for pre-releases are valid but should be clearly marked; they are not the "release" entry. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#semver-v200-communication-obligations]

"What / Why / Impact" format

Each release note bullet answers three questions in one to three short sentences: [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#what-why-impact-format]
One-liner form when all three collapse naturally: [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#what-why-impact-format]
Never omit Impact for MAJOR or Security entries. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#what-why-impact-format]

Breaking-change announcement template

Use this structure for any breaking change, whether shipped in a MAJOR bump or announced as Deprecated in a prior MINOR. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#breaking-change-announcement-template]
- Deprecation and removal must appear as separate changelog entries. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#breaking-change-announcement-template]
- The removal entry in the changelog must cite the deprecation entry by version. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#breaking-change-announcement-template]
- Never remove something that was not previously deprecated in a published release. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#breaking-change-announcement-template]

User-facing vs internal split

Public changelog (CHANGELOG.md, GitHub Release, npm release body): [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#user-facing-vs-internal-split]
- Every change that alters public API surface, CLI flags, config keys, network behavior, or data formats. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#user-facing-vs-internal-split]
- Every security patch. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#user-facing-vs-internal-split]
- Every deprecation and removal. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#user-facing-vs-internal-split]
- Performance improvements visible to the operator (latency, memory, startup time). [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#user-facing-vs-internal-split]
Stays in commit messages / internal docs: [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#user-facing-vs-internal-split]
- Refactors with no behavior change. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#user-facing-vs-internal-split]
- Test additions and coverage improvements. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#user-facing-vs-internal-split]
- CI/CD pipeline changes. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#user-facing-vs-internal-split]
- Code style or formatting sweeps. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#user-facing-vs-internal-split]
- Internal rename of unexported identifiers. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#user-facing-vs-internal-split]
Heuristic: if a consumer of the published artifact could observe the change without reading the source, it belongs in the changelog. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#user-facing-vs-internal-split]

Release note tones by audience

Developer: Remove --legacy-peer-deps default; pass it explicitly if needed (#1243). [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#release-note-tones-by-audience]
End-user: You can now filter cases by severity directly from the dashboard. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#release-note-tones-by-audience]
Executive: Resolved two authentication edge cases that affected enterprise SSO configurations. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#release-note-tones-by-audience]

Bullet structure

Pattern: imperative verb + scope + outcome. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#bullet-structure]
- Start with a capital letter; no trailing period on standalone bullets. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#bullet-structure]
- Avoid past tense ("Added", "Fixed") as the first word - the section header already carries tense. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#bullet-structure]
- Scope narrows the noun: "Fix null-pointer in CaseEnricher.normalize()", not "Fix bug". [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#bullet-structure]
- Outcome states the user-visible result when it's non-obvious. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#bullet-structure]

Linking discipline

Reference issues and PRs as (#1234) or (#1234), not bare dashboard URLs. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#linking-discipline]
Security patches: link to the advisory or CVE, not to an internal ticket. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#linking-discipline]
Migration guides: link to a versioned doc path, not to main or latest which can drift. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#linking-discipline]
Do not embed tracking parameters or redirector URLs in changelog links. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#linking-discipline]

Migration guides — inline vs separate document

Inline (in CHANGELOG.md or release body) when: [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#migration-guides-inline-vs-separate-document]
- The migration is two to five steps and requires no code samples longer than 10 lines. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#migration-guides-inline-vs-separate-document]
- The change is in a patch or minor. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#migration-guides-inline-vs-separate-document]
Separate document (docs/migration/v3-to-v4.md) when: [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#migration-guides-inline-vs-separate-document]
- The migration requires platform-specific steps. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#migration-guides-inline-vs-separate-document]
- Code samples span multiple files or languages. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#migration-guides-inline-vs-separate-document]
- The guide will be linked from support channels, README, or the documentation site. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#migration-guides-inline-vs-separate-document]
- The migration window is long and the guide will be updated over time. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#migration-guides-inline-vs-separate-document]
When linking from CHANGELOG.md to a separate guide, pin the link to a tagged commit or versioned doc URL, not main. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#migration-guides-inline-vs-separate-document]

Major-version release-note structure

The Highlights section should be written last: it summarizes everything else. Never let Highlights duplicate Breaking Changes - cross-reference, do not copy. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#major-version-release-note-structure]

Conventional Commits as upstream input

Conventional Commits (conventionalcommits.org) defines a commit message structure that maps cleanly to changelog sections: [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#conventional-commits-as-upstream-input]
Note: deprecate: is not an official type in the Conventional Commits v1.0.0 spec; teams that use it are relying on a custom type. The spec-compliant form is feat(deprecation): or chore(deprecate):. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#conventional-commits-as-upstream-input]
The commit message body and footer become the raw material for changelog bullets. Tooling can generate a draft; a human must review for clarity and audience appropriateness before publishing. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#conventional-commits-as-upstream-input]

Automation tools

release-please (Google): reads Conventional Commits, opens a Release PR with a generated CHANGELOG.md update and version bump. The writer reviews and edits the PR before merging. Does not write migration guides or executive summaries - those remain manual. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#automation-tools]
changesets (Atlassian/community): requires contributors to add a changeset file (pnpm changeset) describing the change type and summary at PR time. Aggregates into CHANGELOG.md on release. Supports monorepos with per-package versioning. Gives writers the most control over copy because the input is prose, not a commit prefix. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#automation-tools]
semantic-release: fully automated - reads commits, bumps version, publishes, and writes CHANGELOG.md without a human review step. Appropriate for internal libraries or CI-only flows. Not recommended when the changelog is customer-facing and tone matters. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#automation-tools]
What all three leave to the writer: migration guides, executive summaries, breaking-change announcements with migration paths, and any copy that requires audience awareness beyond a commit summary. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#automation-tools]
Monorepo note: for monorepos, prefer per-package CHANGELOG.md files (one per package) over a single root changelog. changesets handles this natively; release-please supports it with per-package configuration. [archived source: https://llms-explorer.com/sources/mdb-context-hub/changelog-and-release-notes/#automation-tools]

Where this helps

Shipping a MAJOR version bump with at least one breaking change and needing to know the full set of obligations, including a dedicated Breaking Changes section, a migration guide, and correct semver signaling. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Writing the same underlying change for two different audiences at once, a terse developer-facing bullet and a benefit-led end-user sentence, without contradicting either. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
A change is being deprecated ahead of a future removal, and the deprecation entry and the eventual removal entry need to correctly cross-reference each other by version. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Deciding whether a migration guide belongs inline in the changelog or as a separate linked document, based on its length and complexity. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.

How to apply this

Draft changelog bullets from Conventional Commits messages as What/Why/Impact statements, with a human review step before publishing, following the release-please or changesets model. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Write a breaking-change announcement using the full template — the change, the migration guide, and the version-bump obligations — before shipping a MAJOR release. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Split one underlying change into parallel release-note entries, developer, end-user, and executive tone, to practice the audience-aware tone shift the format requires. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Compare automation tools such as release-please, changesets, and semantic-release on the same sample repo to see how much human review each one still requires before publishing. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.

Antipatterns

Writing a changelog bullet as a past-tense report, “Added the feature,” instead of letting the section header, Added, Fixed, or Changed, carry the tense. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Omitting the Impact sentence on a MAJOR or Security entry, the two categories where impact must never be left implicit. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Linking to an internal ticket instead of a public advisory or CVE for a security patch, which leaves external readers unable to verify or act on the disclosure. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Letting a migration guide link point to main or latest instead of a versioned doc path, so the linked instructions can silently drift out of sync with the version the reader is actually on. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.

Known issues

deprecate: is not an official type in the Conventional Commits v1.0.0 spec, so teams using it as a commit-message type are relying on a non-standard convention automated changelog tooling may not recognize. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Fully automated tools like semantic-release publish and write the changelog without a human review step, which is appropriate for internal libraries but risky for anything user-facing where tone and accuracy matter. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
A public-versus-internal changelog split requires actively deciding, per change, whether it alters public API surface, CLI flags, config keys, network behavior, or data formats — that judgment call doesn't automate away. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
The Highlights section of a major-version release must be written last and must not duplicate the Breaking Changes section, so it can't be extracted mechanically from earlier sections. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.

Children

Keep a Changelog Spec (frontier)
Semver Communication Obligations (frontier)
Breaking-Change Announcement Patterns (frontier)
What/Why/Impact Format (frontier)
Conventional Commits Mapping (frontier)
Automation Tooling (release-please, semantic-release) (frontier)
Deprecation Notices (frontier)
Migration Guides (frontier)

Frontier under this node: Automation Tooling (release-please, semantic-release), Breaking-Change Announcement Patterns, Conventional Commits Mapping, Deprecation Notices, Keep a Changelog Spec, Migration Guides, Semver Communication Obligations, What/Why/Impact Format

← the whole tree · 3D view· how to read this page