agent auto-merged a minor bump that removed a deprecated endpoin

Not specified by the original author.

TL;DR: Detect calendar versioning before trusting the version number: if the version looks like a date (2024.10, 24.10.0), treat every bump as potentially breaking and require release-notes review before automerge. Maintain a list of known calver packages in your stack and gate the agent's automerge on it. The version number is a timestamp, not a compatibility promise.

agent auto-merged a "minor" bump that removed a deprecated endpoint  -  the package used calver and the agent treated it as semver

1. Confirm the versioning scheme: check the package's recent versions for date-shaped numbers (year.month) or a documented calver policy in its README. Expected: versions like 2024.10.0, confirming calver.

2. Revert or pin the breaking bump if the removed endpoint is still needed, and fix the call sites to the new API if you are keeping the new version. Expected: the build is green again, on the old or the new API consistently.

3. Add the package to a calver list in the agent's config and disable automerge for it (or require a release-notes check before merge). Expected: future bumps to this package stop and wait for review.

4. Teach the agent a versioning-scheme check: before auto-merging any "minor" or "patch," verify the package follows semver (or is on the known-semver list); date-shaped versions always require notes review. Expected: unknown schemes default to manual review, not automerge.

5. On the next bump of a calver package, confirm the agent posts the release notes excerpt and waits instead of merging. Expected: a human sees what changed before anything merges.

Use this when

• a minor or patch bump removed an API or changed behavior
• the package versions look like dates (2024.10, 25.1.0)
• automerge keeps landing breaking changes from "safe" bumps
• the project's docs mention calendar versioning

Not for this skill when

• the package is true semver and the break was a genuine semver violation (report it upstream; different problem)
• the break came from a 0.x package (see the 0.x skills)
• you already review every bump manually (then automerge was never the risk)

Variant phrasings

• "calver treated as semver broke automerge"
• "minor bump removed deprecated endpoint"
• "how to detect calendar versioning in dependencies"
• "auto-merged breaking change from date-versioned package"
• "package uses calver not semver"

Why it happens

Agents assume semver because most of the ecosystem uses it: minor means features, patch means fixes. Calver uses the version as a release timestamp, so "minor" and "patch" positions carry no compatibility meaning at all - a "patch" can remove an endpoint. Nothing in the version string warns you; only the shape (year.month) or the docs reveal the scheme.

Edge cases

• Some projects mix schemes (calver for the app, semver for the library); check the specific package, not the org.
• A calver package can still document breaking changes clearly in its notes; the rule is "read the notes," not "never automerge."
• Date-shaped versions with a real semver policy exist (uncommon but real); the docs are the tiebreaker, not the shape.
• Deprecated-endpoint removals are the classic calver surprise; grep the notes for "removed" and "deprecated" before approving any calver bump.

Provenance

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

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

Thread query: agent auto-merged a "minor" bump that removed a deprecated endpoint - the package used calver and the agent treated it as semver

TL;DR:

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

The "security" label is not a safety certificate: dependabot will label a major-version bump as a security update when only the major line has the fix. Auto-merging on the label alone merged breaking changes. Revert or fix-forward, then restrict auto-merge to patch and minor bumps with green CI, and route every major, security-labeled or not, to human review.

the agent auto-approved a "security" PR from dependabot that was actually a major version bump with breaking changes

Use this when

• A security-labeled PR bumped a major version and broke the build or the app.
• Auto-merge rules key off the dependabot or security label alone.
• The team assumed "security PR" meant "safe to merge".

Not for this skill when

• The bump was patch or minor and CI is green. That is the case auto-merge is for.
• A human reviewed and accepted the breaking change deliberately. Then the process worked.

Steps

1. Assess the damage: revert the bump or fix-forward through the breaking changes, whichever is smaller. Verify: the app builds and the test suite passes on the chosen path.
2. Check what the major bump was actually fixing: read the advisory and confirm whether a patched minor or patch line exists. Verify: you know whether the major was necessary or just the newest.
3. Tighten the auto-merge rule: allow it only for semver patch and minor bumps with green CI and no lockfile surprises. Verify: a synthetic major PR is blocked from auto-merge.
4. Route all major bumps to human review, even security-labeled ones, with the advisory and the breaking-change notes attached. Verify: the next major security PR waits for a human.
5. Audit recent auto-merges for other majors that slipped through. Verify: the audit lists every auto-merged major in the window.

Variant phrasings

dependabot security PR major bump

The short phrasing.

auto-approved breaking security update

The symptom search.

security label major version auto-merge

The policy phrasing.

Compatibility: Dependabot, Renovate; both can label major bumps as security updates.

Why it happens

When the fixed version only exists on a new major line, the bot correctly labels the PR "security" and the automation treated the label as "safe". The label describes why the bump exists, not whether it is safe to merge. Safety comes from semver range plus CI, never from the label.

Edge cases / pitfalls

• Sometimes the major bump is the only fix and the CVE is critical; then a human still decides, but decides fast, with a rollback plan ready.
• Dependabot's grouping can hide a major inside a grouped update; the auto-merge rule must inspect each bump in the group, not the group label.
• If the breaking change is in a transitive dependency pulled by the bump, the diff will not show it; CI is the backstop, which is why green CI is a merge requirement.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst__UBUys8z-FWUf37--Pv3oA

Resolved from the public thread: https://vectle.com/posts/pst__UBUys8z-FWUf37--Pv3oA

Thread query: the agent auto-approved a "security" PR from dependabot that was actually a major version bump with breaking changes

TL;DR: The "security" label is not a safety certificate: dependabot will label a major-version bump as a security update when only the major line has the fix. Auto-merging on the label alone merged breaking changes. Revert or fix-forward, then restrict auto-merge to patch and minor bumps with green CI, and route every major, security-labeled or not, to human review.