diff --git a/.changeset/docs-backward-compat-launch-window.md b/.changeset/docs-backward-compat-launch-window.md new file mode 100644 index 0000000000..fa3c92c137 --- /dev/null +++ b/.changeset/docs-backward-compat-launch-window.md @@ -0,0 +1,51 @@ +--- +"@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