changelog missing entry for breaking change, release failed review

TL;DR

Write the missing breaking-change entry into the changelog now: what changed, who it affects, and exactly how to migrate, then re-request the release review. Reviewers reject releases that hide breaking changes because downstream users cannot assess upgrade risk from the notes. For the next release, enforce conventional commits with breaking-change markers so the entry is generated automatically.

The error

changelog missing entry for breaking change, release failed review

Steps

1. Find the breaking commits: git log v1.4.0..v1.5.0 --oneline and flag anything that removes or renames public API, changes defaults, or drops supported input. Expected: a short list of candidate commits.
2. For each one, write a changelog entry under a "Breaking changes" heading with three parts: what changed, who is affected, and the migration steps. Expected: a reviewer can upgrade using only your entry.
3. Re-read the full diff once more for silent breaks (renamed config keys, changed defaults, removed parameters). Expected: no breaking change remains undocumented.
4. Commit the changelog update and re-request review. Expected: the review checklist item for breaking changes is satisfied.
5. Prevent repeats: require breaking-change footers or ! markers in commit messages, and add a CI check that fails when the diff touches public API without a changelog entry.

Use this when

• A release review failed specifically over a missing breaking-change note.
• Users report a breaking upgrade that the changelog never mentioned.
• You are writing release notes and suspect something breaking slipped in quietly.

Not for this skill when

• The release has no breaking changes - nothing to document.
• The review failed for a different reason (version number, missing tests, sign-off).
• You need to decide whether a change counts as breaking - that is an API-design call, not a changelog fix.

Variant phrasings

release rejected: breaking change not documented

Same review failure, different phrasing. Same fix.

changelog does not mention the breaking change

Same gap found by a user instead of a reviewer. Same fix.

missing migration notes for breaking release

Same fix, with emphasis on the migration steps reviewers look for.

Why it happens

Breaking changes often land as drive-by edits inside feature commits, so whoever writes the notes never notices them. Generated changelogs only surface what the commit messages declare, and hand-written notes depend on the author's memory of the diff. Either way the entry is missing because nothing in the process forced it to exist.

Edge cases

• Behavior changes with no API diff (a default flips, an error becomes silent) are the most commonly missed. Grep the diff for changed defaults and constants, not just signatures.
• Deprecation removals: if the removal was announced two versions ago, the entry still belongs in the breaking section with a pointer to the original notice.
• Multiple breaking changes: list each separately with its own migration steps. One vague paragraph does not pass review.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_pj0nS2KIBKlBswWrCLVing