From ec82fc089b3e84fb434c8eae00a1c76cf744157f Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 31 Aug 2026 15:58:57 +0000 Subject: [PATCH 1/2] docs(protocol): restate the stale pre-1.0 disclaimer as the launch-window rule (#13779) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Backward Compatibility page closed with a 'Pre-1.0 Disclaimer' saying MINOR may break 'during the 0.x development phase', with the full policy taking effect at 1.0.0. The published stack is at 17.2.0, so that reads as dead text — leaving the page's opening SemVer table (MINOR keeps existing code working) as the answer a customer takes away. That is inverted. The substance survived; only the 0.x/1.0.0 framing died. Breaking changes ship as MINOR today, per .changeset/config.json (69 published packages in one lockstep fixed group), scripts/check-changeset-no-major.mjs (a currently-enforcing CI guard), packages/spec/CHANGELOG.md (17.2.0's Minor Changes carries a **BREAKING** entry) and content/docs/releases/ v13/v14/v15/v17. Deleting the paragraph would have silently strengthened a customer-facing compatibility promise. It is restated instead, naming the covered surface (all 69 published packages, none exempt) and marked as overriding the tables above. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01Pk26oZ12t5N1hwGW1m1MgC --- .../docs-backward-compat-launch-window.md | 49 +++++++++++++++++++ .../docs/protocol/backward-compatibility.mdx | 22 ++++++++- 2 files changed, 69 insertions(+), 2 deletions(-) create mode 100644 .changeset/docs-backward-compat-launch-window.md diff --git a/.changeset/docs-backward-compat-launch-window.md b/.changeset/docs-backward-compat-launch-window.md new file mode 100644 index 0000000000..9f9539eb01 --- /dev/null +++ b/.changeset/docs-backward-compat-launch-window.md @@ -0,0 +1,49 @@ +--- +"@objectstack/docs": patch +--- + +fix(docs): the Backward Compatibility page said MINOR may break "during 0.x" — restate it as the launch-window rule it actually is (#13779) + +`content/docs/protocol/backward-compatibility.mdx` closed with a `Pre-1.0 +Disclaimer` reading: + +> During the **0.x** development phase, MINOR versions may contain breaking +> changes. The full backward compatibility policy takes effect starting with +> version **1.0.0**. + +The published stack is at **17.2.0**, so a reader dismisses that paragraph as +obviously stale and is left with the page's opening SemVer table, which says a +MINOR keeps existing code working. **That is the wrong way round.** The +disclaimer's *substance* is the part that survived; only its `0.x` / `1.0.0` +framing died. + +Deleting the paragraph would therefore have silently **strengthened** a +customer-facing compatibility promise into one the repo contradicts on every +release. Four independent sources say breaking changes ship as MINOR today: + +- **`.changeset/config.json`** — all **69** published packages sit in one + Changesets `fixed` group (`check:changeset-fixed`: *"fixed group is in sync + with 69 public workspace packages"*), so no published surface is exempt and a + single `major` would promote the whole stack. +- **`scripts/check-changeset-no-major.mjs`** — a wired, currently-enforcing CI + guard (`.changeset/pre.json` is absent, so the RC exemption is not in play) + whose header states the convention outright: *"During the launch window we ship + breaking changes as `minor`."* `--list` reports **559 pending changesets, 0 + declaring a major**. +- **`packages/spec/CHANGELOG.md`** — the `17.2.0` **Minor Changes** section + carries an entry marked `**BREAKING**` (the `http_request_errors_total` + retirement under ADR-0049). +- **`content/docs/releases/`** — v13, v14, v15 and v17 already tell customers + this. v15.1.0: *"Strict-semver breaking, shipped in a minor under the + launch-window policy."* v17: *"17.1.0 and 17.2.0 are minors by version number, + not by blast radius."* + +The section is retitled `Launch Window: MINOR Releases Can Contain Breaking +Changes` and now states the rule definitely rather than hedging it: which +surfaces it covers (all 69), that it is gate-enforced, what an upgrader should do +instead of trusting the version number, that MAJORs still happen when breaking +density demands one, and that it overrides the tables above wherever they +disagree. + +Nothing links to the old `#pre-10-disclaimer` anchor (grepped repo-wide), so the +retitle breaks no inbound reference. diff --git a/content/docs/protocol/backward-compatibility.mdx b/content/docs/protocol/backward-compatibility.mdx index 9f5372f1c3..d92e7ef31a 100644 --- a/content/docs/protocol/backward-compatibility.mdx +++ b/content/docs/protocol/backward-compatibility.mdx @@ -174,12 +174,30 @@ The `@objectstack/spec` package provides additional stability guarantees: --- -## Pre-1.0 Disclaimer +## Launch Window: MINOR Releases Can Contain Breaking Changes -During the **0.x** development phase, MINOR versions may contain breaking changes. The full backward compatibility policy takes effect starting with version **1.0.0**. +**This exception overrides the MAJOR/MINOR mapping above — read it before you plan an upgrade.** Every published `@objectstack/*` package versions in **lockstep**, and while the launch window is open a breaking change ships as a **MINOR** release rather than burning a MAJOR. The current release, **17.2.0**, is a MINOR and it contains a documented breaking change. +### Which surfaces this covers + +**All of them.** This is not scoped to an experimental corner or a pre-release channel: all **69** packages published from this repository belong to a single Changesets `fixed` group, so they share one version number and one policy. No published surface is exempt. + +The convention is enforced rather than informal — `scripts/check-changeset-no-major.mjs` fails any pull request that introduces a `major` bump, because under lockstep a single `major` on one package would promote the entire stack. + +### What this means for an upgrade + +- **Do not read a MINOR bump as safe to take unattended.** Read the [release notes](/docs/releases) for the version you are moving to: they lead with breaking changes and carry the migration steps. +- **Pin exact versions** instead of caret ranges if you cannot review each MINOR before it lands. +- **Diff your own metadata** across the upgrade with `os diff --breaking-only`. + +MAJOR releases do still happen — 17.0.0 was cut precisely because its breaking density was too high to carry `^16.x` consumers across on a caret range — but an individual breaking change does not, on its own, force one. + +### When it stops applying + +The versioning tables and deprecation timeline above describe the policy in its settled form; they take full effect when the launch window closes and a breaking change once again requires a MAJOR. Until then, **this section is the operative rule wherever the two disagree.** + --- ## Reporting Compatibility Issues From a8c19e211e164677f16b1cf2469bf6930f01d621 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 31 Aug 2026 16:04:56 +0000 Subject: [PATCH 2/2] docs(changeset): declare the ADR-0087 disposition for the docs-only correction (#13779) Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01Pk26oZ12t5N1hwGW1m1MgC --- .changeset/docs-backward-compat-launch-window.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.changeset/docs-backward-compat-launch-window.md b/.changeset/docs-backward-compat-launch-window.md index 9f9539eb01..fa3c92c137 100644 --- a/.changeset/docs-backward-compat-launch-window.md +++ b/.changeset/docs-backward-compat-launch-window.md @@ -47,3 +47,5 @@ disagree. Nothing links to the old `#pre-10-disclaimer` anchor (grepped repo-wide), so the retitle breaks no inbound reference. + +