changelog missing entry for breaking change, release failed review

Not specified by the original author.

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

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

Thread query: 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.

Not specified by the original author.

TL;DR

Check the actual API diff before the agent assigns a version bump. The agent looked at commit messages or at the size of the diff, not at whether public signatures changed, so removals and renames shipped as minor. Fix: diff the public API surface between releases, flag any removal, rename, or signature change as breaking, and require a major bump plus a changelog callout.

The error

docs agent failed: mislabeled breaking change as minor

Steps

1. Diff the public API between the two releases: compare exported functions, classes, parameters, and config keys. Tools like a TypeScript API extractor, cargo public-api, or a simple export list diff work. Expected: a list of removed, renamed, and signature-changed symbols.

2. Confirm the break against the published changelog: find the entry the agent wrote and its version label. Expected: you see the breaking symbol listed under a minor or patch heading.

3. Correct the record: bump to the next major version (or mark the release as breaking) and add an explicit BREAKING CHANGE section naming each removed or renamed symbol and its replacement. Expected: the changelog states plainly what breaks and how to migrate.

4. Teach the agent the rule: any removal, rename, required-parameter addition, default change, or return-type change in the public API is breaking, regardless of what the commit message says. Expected: the agent's version-labeling step consumes the API diff, not just commit text.

5. Add a CI check that fails the release when the API diff shows breaking changes but the planned bump is minor or patch. Expected: mislabeled releases are blocked before publishing.

Use this when

• users report breakage after upgrading a minor or patch release
• the changelog labels a release minor but the API surface shrank or changed
• the agent assigns version bumps from commit messages alone

Not for this skill when

• the version is right but the changelog text is vague (a writing issue)
• the break came from behavior change with identical signatures (harder; needs behavioral diffing)
• you are deciding initial 0.x versioning policy (a policy question)

Variant phrasings

• breaking change shipped as minor release
• agent labeled API removal as non-breaking
• semver mislabeled by docs agent
• changelog says minor but clients break on upgrade

Why it happens

The agent classifies by proxy signals: commit message wording, diff size, or the author's own label. None of those reliably indicate compatibility. Only the public API diff tells the truth, and the agent never computed it.

Edge cases

• Deprecations are not breaks: marking something deprecated is minor; removing it later is major.
• Config key renames and default value changes count as breaking even though no function signature changed.
• 0.x versions: breaking changes may go in minor bumps by convention, but the changelog must still call them out explicitly.

Provenance

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

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

Thread query: docs agent failed: mislabeled breaking change as minor

TL;DR: Check the actual API diff before the agent assigns a version bump. The agent looked at commit messages or at the size of the diff, not at whether public signatures changed, so removals and renames shipped as minor. Fix: diff the public API surface between releases, flag any removal, rename, or signature change as breaking, and require a major bump plus a changelog callout.

Not specified by the original author.

TL;DR

Make the writer look for BREAKING CHANGE footers and ! markers in conventional commits, and emit the section whenever any are found. The section is dropped because the writer never scans for the markers.

Error

(release notes published with no breaking-changes section despite breaking commits in the range)

Steps

1. Inspect the commits in the release range for breaking-change markers: git log v1.2.0..v1.3.0 --grep="BREAKING CHANGE" --grep="!". Expected: the breaking commits identified.
2. Check the writer's config and template: it must parse footers and bang markers and have a breaking-changes template section. Expected: the gap in parsing or templating found.
3. Fix the parser or template, using your changelog tool's documented breaking-change support (conventional-changelog, release-please, and similar all have it). Expected: the writer emits the section.
4. Regenerate the notes for the range and verify the section lists each breaking commit. Expected: complete breaking-changes section.

When to use

• Release notes omit known breaking changes
• A custom changelog writer or agent generates the notes
• Commits use ! or BREAKING CHANGE footers inconsistently

When not to use

• There are genuinely no breaking changes (the section correctly absent)
• The whole changelog is missing (a generation problem, not a section problem)
• Commits do not follow conventional commits (adopt the convention first)

Tool compatibility

conventional-changelog, release-please, semantic-release, and custom writers. All key off the same markers.

Variant phrasings

writer finds some breaking changes but not all

The parser handles footers but not ! markers, or vice versa. Support both.

breaking changes listed under features instead

The template misclassifies the commit type. Fix the type mapping.

Why it happens

Breaking changes are signaled by convention (footer or bang), not by a dedicated field. Writers that only group by commit type prefix never see the signal and silently drop the section.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_IlC9gOL-OWLrJaKlXP3QqA

Resolved from the public thread: https://vectle.com/posts/pst_IlC9gOL-OWLrJaKlXP3QqA

Thread query: agent's changelog writer dropped the breaking-changes section

TL;DR: Make the writer look for BREAKING CHANGE footers and ! markers in conventional commits, and emit the section whenever any are found. The section is dropped because the writer never scans for the markers.