From b3305973409d8003929ad9236ccec787be981fd0 Mon Sep 17 00:00:00 2001 From: leemour Date: Mon, 19 Oct 2026 13:56:12 +0200 Subject: [PATCH 1/2] docs(standards): WC-REL-9 counts only changes that make a CLI change its code The weekly limit on breaking shared-library export changes now counts a change only when at least one consuming CLI has to change its code to take it. The library's CI proves it: cli-core's parity.yml builds tg-cli, max-cli and whatsapp-cli against every pull request. A type-level change that all of them build and pass with, unchanged, does not count toward the week; its changelog still marks it "may break callers" for outside users. The rule exists so the CLIs do not chase versions. It blocked cli-core #1605, which changed no CLI. Ruling: NEED-1552. Co-Authored-By: Claude Opus 5.5 (1M context) --- CHANGELOG.md | 10 ++++++++++ docs/standards/releases.md | 17 ++++++++++------- 2 files changed, 20 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 480389f..8903b69 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,16 @@ Versions before 0.8.0 are in the [git tags](https://github.com/WireCatLabs/cli-b Every entry says what changed as a caller sees it, why, and what to watch for — the rules are [`docs/dev/CONVENTIONS.md`](docs/dev/CONVENTIONS.md#the-changelog). +## Unreleased + +### Added + +- **WC-REL-9 counts a shared-library change toward its once-a-week limit only when a CLI must change its code to take + it.** The library's own CI proves it: cli-core builds tg-cli, max-cli and whatsapp-cli against every pull request, + and a change all three pass with, unchanged, ships in any release. The limit exists so the CLIs do not chase + versions, and such a change gives them nothing to chase. Its changelog still marks it "may break callers" for + outside users. + ## 0.47.1 — 19.10.2026 ### Added diff --git a/docs/standards/releases.md b/docs/standards/releases.md index b7dc073..18846bb 100644 --- a/docs/standards/releases.md +++ b/docs/standards/releases.md @@ -98,14 +98,17 @@ on the [CI](ci.md) page. - **Exceptions:** memo, drive and zoom have no gap in their `bin/release` today. - **Applies to:** messenger CLIs (gap); shared libraries (no gap). **Since:** cli-base 0.41.0. **Rulings:** NEED-854. -### WC-REL-9 · A breaking change to a stable shared-library export ships at most once a week - -- **Why:** each such change makes every CLI change too; batching them keeps the CLIs on one version. -- **Enforced by:** review only. -- **Example:** gather breaking export changes into one release a week. Bump the library in every CLI that uses it on - the same day. +### WC-REL-9 · A change to a stable shared-library export that makes a CLI change its code ships at most once a week + +- **Why:** the limit keeps the CLIs from chasing versions; a change that no CLI has to follow gives them nothing to + chase. +- **Enforced by:** `cli-core: parity.yml`. +- **Example:** cli-core's CI builds tg-cli, max-cli and whatsapp-cli against every pull request. A change to a stable + export that all three still build and pass with, unchanged, does not count toward the week; its changelog still + lists it under "Changed — may break callers" for outside users. A change that makes any CLI fail counts: gather + those into one release a week, and bump the library in every CLI that uses it on the same day. - **Exceptions:** none. -- **Applies to:** shared libraries. **Since:** cli-base 0.41.0. **Rulings:** NEED-473. +- **Applies to:** shared libraries. **Since:** cli-base 0.41.0. **Rulings:** NEED-473, NEED-1552. ### WC-REL-10 · A messenger CLI is released only with a release report the owner signed for that commit From 6df890381179cffe402b81636697bb6737fd8275 Mon Sep 17 00:00:00 2001 From: leemour Date: Mon, 19 Oct 2026 13:57:45 +0200 Subject: [PATCH 2/2] docs(standards): WC-REL-9 names the parity result and counts unseen behaviour changes The parity jobs build each CLI's main and check its command manifest; they do not run the CLIs' tests. So the rule now says what the test is: a change is free only when all three jobs pass with each CLI's main unchanged. It still counts when a job fails, when it passes only against a CLI branch made for the change, or when it compiles but changes behaviour a CLI must adapt to. Parity cannot see that last case, so in doubt the change counts. Enforced by now says parity decides which changes count and review keeps the week. Co-Authored-By: Claude Opus 5.5 (1M context) --- CHANGELOG.md | 9 +++++---- docs/standards/releases.md | 12 +++++++----- 2 files changed, 12 insertions(+), 9 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8903b69..15ff29d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,10 +13,11 @@ Every entry says what changed as a caller sees it, why, and what to watch for ### Added - **WC-REL-9 counts a shared-library change toward its once-a-week limit only when a CLI must change its code to take - it.** The library's own CI proves it: cli-core builds tg-cli, max-cli and whatsapp-cli against every pull request, - and a change all three pass with, unchanged, ships in any release. The limit exists so the CLIs do not chase - versions, and such a change gives them nothing to chase. Its changelog still marks it "may break callers" for - outside users. + it.** cli-core's parity jobs build tg-cli, max-cli and whatsapp-cli from their `main` against every pull request. + A change all three pass with, unchanged, may ship in any release. A change that fails a job, passes only against a + CLI branch made for it, or changes behaviour a CLI must adapt to still counts; when in doubt, it counts. The limit + exists so the CLIs do not chase versions, and a change they need not follow gives them nothing to chase. Its + changelog still marks it "may break callers" for outside users. ## 0.47.1 — 19.10.2026 diff --git a/docs/standards/releases.md b/docs/standards/releases.md index 18846bb..d4b0f96 100644 --- a/docs/standards/releases.md +++ b/docs/standards/releases.md @@ -102,11 +102,13 @@ on the [CI](ci.md) page. - **Why:** the limit keeps the CLIs from chasing versions; a change that no CLI has to follow gives them nothing to chase. -- **Enforced by:** `cli-core: parity.yml`. -- **Example:** cli-core's CI builds tg-cli, max-cli and whatsapp-cli against every pull request. A change to a stable - export that all three still build and pass with, unchanged, does not count toward the week; its changelog still - lists it under "Changed — may break callers" for outside users. A change that makes any CLI fail counts: gather - those into one release a week, and bump the library in every CLI that uses it on the same day. +- **Enforced by:** `cli-core: parity.yml` (it decides which changes count; review keeps the week). +- **Example:** cli-core's parity jobs build tg-cli, max-cli and whatsapp-cli from their `main` against every pull + request. A change to a stable export counts unless all three jobs pass with each CLI's `main` unchanged; its + changelog still lists it under "Changed — may break callers" for outside users. It counts when a job fails, when it + passes only against a CLI branch made for the change, and when it compiles but changes behaviour that any CLI must + adapt to. Parity cannot see that last case, so when in doubt the change counts. Gather the changes that count into + one release a week, and bump the library in every CLI that uses it on the same day. - **Exceptions:** none. - **Applies to:** shared libraries. **Since:** cli-base 0.41.0. **Rulings:** NEED-473, NEED-1552.