process: define versioning policy for ported breaking changes — two unreleased `!` commits sit under v2.8.0; consider release automation

[IgorShevchik]

Background

Surfaced during the June 2026 multi-angle project audit (CTO review).

Problem

main currently carries ~13 unreleased commits over v2.8.0, including two breaking ones: 081a979 feat(InputMenu)! (#68) and 5da53b6 fix(components)! (#72). The CHANGELOG is hand-written and releases are manual chore(release) commits (no changesets/release-please).

If the next release ships as 2.9.0, semver is violated and consumer trust erodes — and the per-commit upstream sync (#75) will keep generating exactly this class of decision, so it needs a standing policy rather than per-release judgment calls.

Actions

• Publish a one-paragraph versioning policy in AGENTS.md / contributing docs: either any ported ! commit ⇒ next release is a major, or an explicitly documented v2-line exception (e.g. "breaking changes inherited from upstream v4 ports are released in minors during the 2.x adaptation phase, flagged in the CHANGELOG ⚠️ section") — but written down, before the next release.
• Consider release automation (release-please or changesets): commit history is already 100% conventional-commits via squash-merged PRs, so versions + CHANGELOG can be derived mechanically; this also removes single-maintainer release friction.
• Make the breaking-change call part of the sync-port checklist in .sync/PORTING.md.

Priority: P2 — decide before the next release ships.

[IgorShevchik]

Closed by #468. Two of the three actions were already done by the time anyone came back to this; the third was the interesting one.

Publish a versioning policy — done. releasing.md carries the version arithmetic table, and it takes the strict branch the issue offered first: any BREAKING CHANGE or ! makes the next release a major, with no v2-line exception. No "breaking changes inherited from upstream are released in minors during the adaptation phase" escape hatch. Good — that hatch would have been quietly load-bearing forever.

Consider release automation — done. release-please. The issue's reasoning ("commit history is already 100% conventional-commits via squash-merged PRs, so versions and CHANGELOG can be derived mechanically") is exactly how it turned out.

Make the breaking-change call part of the sync-port checklist — this is the one that was missing, and automation is precisely why it matters more now than when the issue was filed. Back then the CHANGELOG was hand-written and a human read the diff, so a dropped ! was a cosmetic slip someone would catch. Today release-please reads the squashed subject and nothing else. Drop the ! and the port ships a breaking change as a minor: lint, typecheck, test and build all pass, the code is correct, and only the version is wrong — wrong for every consumer who trusted the range.

So PORTING.md §6 now says to carry the marker across, and says it in both directions, because a port is not a copy:

when the upstream commit is breaking, the PR title is too. Restate the break in our own terms rather than copying upstream's wording, since what breaks here can differ: a divergence recorded in §2 may absorb the change, in which case say so in the ledger entry and drop the marker deliberately. The reverse also happens — a faithful port can break b24ui where it did not break upstream, because this fork's prop or slot surface is not the same.

§7 gained the reviewer half in the same PR. A rule that only the person doing the port applies is a rule with one pair of eyes on it, and this one has no downstream check at all — release-please takes the subject at its word.

The concrete worry that opened this issue — 081a979 feat(InputMenu)! and 5da53b6 fix(components)! sitting unreleased under v2.8.0 — resolved itself long ago in the v2.9.0 line. What is left is the standing procedure, which is what you asked for: "written down, before the next release." It is written down, and the next release will be the first to run under it.

Thanks for filing this one. It aged well — the part that was still open in August was the part that only became important because the automation landed.

---

Generated by Claude Code