docs(protocol): the pre-1.0 disclaimer's substance survived — restate it as the launch-window rule instead of deleting it#13895

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
os-project-manager merged 2 commits into from
Aug 31, 2026
Merged

docs(protocol): the pre-1.0 disclaimer's substance survived — restate it as the launch-window rule instead of deleting it #13895

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ec82fc0
docs(protocol): restate the stale pre-1.0 disclaimer as the launch-wi…
claude Aug 31, 2026
a8c19e2
docs(changeset): declare the ADR-0087 disposition for the docs-only c…
claude Aug 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 51 additions & 0 deletions .changeset/docs-backward-compat-launch-window.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -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.

<!-- adr-0087: not-required (unpublished) The only bumped package is @objectstack/docs, which is `private: true` and absent from the Changesets `fixed` group, so nothing here reaches a published surface. This changeset removes, renames and narrows nothing; the BREAKING wording in the body quotes changelog entries that already shipped, and is not a breaking change declared by this diff. -->
22 changes: 20 additions & 2 deletions content/docs/protocol/backward-compatibility.mdx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -174,12 +174,30 @@ The `@objectstack/spec` package provides additional stability guarantees:

---

## Pre-1.0 Disclaimer
## Launch Window: MINOR Releases Can Contain Breaking Changes

<Callout type="warn">
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.
</Callout>

### 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 <before> <after> --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
Expand Down
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all 
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
docs(protocol): the pre-1.0 disclaimer's substance survived — restate it as the launch-window rule instead of deleting it#13895

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

os-project-manager
merged 2 commits into

from

Aug 31, 2026
 Merged


docs(protocol): the pre-1.0 disclaimer's substance survived — restate it as the launch-window rule instead of deleting it
#13895
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
ec82fc0

docs(protocol): restate the stale pre-1.0 disclaimer as the launch-wi…


claude Aug 31, 2026
a8c19e2

docs(changeset): declare the ADR-0087 disposition for the docs-only c…


claude Aug 31, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


51 changes: 51 additions & 0 deletions
.changeset/docs-backward-compat-launch-window.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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.

<!-- adr-0087: not-required (unpublished) The only bumped package is @objectstack/docs, which is `private: true` and absent from the Changesets `fixed` group, so nothing here reaches a published surface. This changeset removes, renames and narrows nothing; the BREAKING wording in the body quotes changelog entries that already shipped, and is not a breaking change declared by this diff. -->

22 changes: 20 additions & 2 deletions
content/docs/protocol/backward-compatibility.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -174,12 +174,30 @@ The `@objectstack/spec` package provides additional stability guarantees:

---

## Pre-1.0 Disclaimer
## Launch Window: MINOR Releases Can Contain Breaking Changes

<Callout type="warn">
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.
</Callout>

### 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 <before> <after> --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
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix");
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
docs(protocol): the pre-1.0 disclaimer's substance survived — restate it as the launch-window rule instead of deleting it#13895

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

os-project-manager
merged 2 commits into

from

Aug 31, 2026
 Merged


docs(protocol): the pre-1.0 disclaimer's substance survived — restate it as the launch-window rule instead of deleting it
#13895
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
ec82fc0

docs(protocol): restate the stale pre-1.0 disclaimer as the launch-wi…


claude Aug 31, 2026
a8c19e2

docs(changeset): declare the ADR-0087 disposition for the docs-only c…


claude Aug 31, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


51 changes: 51 additions & 0 deletions
.changeset/docs-backward-compat-launch-window.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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.

<!-- adr-0087: not-required (unpublished) The only bumped package is @objectstack/docs, which is `private: true` and absent from the Changesets `fixed` group, so nothing here reaches a published surface. This changeset removes, renames and narrows nothing; the BREAKING wording in the body quotes changelog entries that already shipped, and is not a breaking change declared by this diff. -->

22 changes: 20 additions & 2 deletions
content/docs/protocol/backward-compatibility.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -174,12 +174,30 @@ The `@objectstack/spec` package provides additional stability guarantees:

---

## Pre-1.0 Disclaimer
## Launch Window: MINOR Releases Can Contain Breaking Changes

<Callout type="warn">
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.
</Callout>

### 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 <before> <after> --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
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms");
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
docs(protocol): the pre-1.0 disclaimer's substance survived — restate it as the launch-window rule instead of deleting it#13895

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

os-project-manager
merged 2 commits into

from

Aug 31, 2026
 Merged


docs(protocol): the pre-1.0 disclaimer's substance survived — restate it as the launch-window rule instead of deleting it
#13895
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
ec82fc0

docs(protocol): restate the stale pre-1.0 disclaimer as the launch-wi…


claude Aug 31, 2026
a8c19e2

docs(changeset): declare the ADR-0087 disposition for the docs-only c…


claude Aug 31, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


51 changes: 51 additions & 0 deletions
.changeset/docs-backward-compat-launch-window.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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.

<!-- adr-0087: not-required (unpublished) The only bumped package is @objectstack/docs, which is `private: true` and absent from the Changesets `fixed` group, so nothing here reaches a published surface. This changeset removes, renames and narrows nothing; the BREAKING wording in the body quotes changelog entries that already shipped, and is not a breaking change declared by this diff. -->

22 changes: 20 additions & 2 deletions
content/docs/protocol/backward-compatibility.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -174,12 +174,30 @@ The `@objectstack/spec` package provides additional stability guarantees:

---

## Pre-1.0 Disclaimer
## Launch Window: MINOR Releases Can Contain Breaking Changes

<Callout type="warn">
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.
</Callout>

### 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 <before> <after> --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
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links");
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
docs(protocol): the pre-1.0 disclaimer's substance survived — restate it as the launch-window rule instead of deleting it#13895

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

os-project-manager
merged 2 commits into

from

Aug 31, 2026
 Merged


docs(protocol): the pre-1.0 disclaimer's substance survived — restate it as the launch-window rule instead of deleting it
#13895
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
ec82fc0

docs(protocol): restate the stale pre-1.0 disclaimer as the launch-wi…


claude Aug 31, 2026
a8c19e2

docs(changeset): declare the ADR-0087 disposition for the docs-only c…


claude Aug 31, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


51 changes: 51 additions & 0 deletions
.changeset/docs-backward-compat-launch-window.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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.

<!-- adr-0087: not-required (unpublished) The only bumped package is @objectstack/docs, which is `private: true` and absent from the Changesets `fixed` group, so nothing here reaches a published surface. This changeset removes, renames and narrows nothing; the BREAKING wording in the body quotes changelog entries that already shipped, and is not a breaking change declared by this diff. -->

22 changes: 20 additions & 2 deletions
content/docs/protocol/backward-compatibility.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -174,12 +174,30 @@ The `@objectstack/spec` package provides additional stability guarantees:

---

## Pre-1.0 Disclaimer
## Launch Window: MINOR Releases Can Contain Breaking Changes

<Callout type="warn">
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.
</Callout>

### 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 <before> <after> --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
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default");
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
docs(protocol): the pre-1.0 disclaimer's substance survived — restate it as the launch-window rule instead of deleting it#13895

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

os-project-manager
merged 2 commits into

from

Aug 31, 2026
 Merged


docs(protocol): the pre-1.0 disclaimer's substance survived — restate it as the launch-window rule instead of deleting it
#13895
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
ec82fc0

docs(protocol): restate the stale pre-1.0 disclaimer as the launch-wi…


claude Aug 31, 2026
a8c19e2

docs(changeset): declare the ADR-0087 disposition for the docs-only c…


claude Aug 31, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


51 changes: 51 additions & 0 deletions
.changeset/docs-backward-compat-launch-window.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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.

<!-- adr-0087: not-required (unpublished) The only bumped package is @objectstack/docs, which is `private: true` and absent from the Changesets `fixed` group, so nothing here reaches a published surface. This changeset removes, renames and narrows nothing; the BREAKING wording in the body quotes changelog entries that already shipped, and is not a breaking change declared by this diff. -->

22 changes: 20 additions & 2 deletions
content/docs/protocol/backward-compatibility.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -174,12 +174,30 @@ The `@objectstack/spec` package provides additional stability guarantees:

---

## Pre-1.0 Disclaimer
## Launch Window: MINOR Releases Can Contain Breaking Changes

<Callout type="warn">
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.
</Callout>

### 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 <before> <after> --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
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers");
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
docs(protocol): the pre-1.0 disclaimer's substance survived — restate it as the launch-window rule instead of deleting it#13895

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

os-project-manager
merged 2 commits into

from

Aug 31, 2026
 Merged


docs(protocol): the pre-1.0 disclaimer's substance survived — restate it as the launch-window rule instead of deleting it
#13895
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
ec82fc0

docs(protocol): restate the stale pre-1.0 disclaimer as the launch-wi…


claude Aug 31, 2026
a8c19e2

docs(changeset): declare the ADR-0087 disposition for the docs-only c…


claude Aug 31, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


51 changes: 51 additions & 0 deletions
.changeset/docs-backward-compat-launch-window.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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.

<!-- adr-0087: not-required (unpublished) The only bumped package is @objectstack/docs, which is `private: true` and absent from the Changesets `fixed` group, so nothing here reaches a published surface. This changeset removes, renames and narrows nothing; the BREAKING wording in the body quotes changelog entries that already shipped, and is not a breaking change declared by this diff. -->

22 changes: 20 additions & 2 deletions
content/docs/protocol/backward-compatibility.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -174,12 +174,30 @@ The `@objectstack/spec` package provides additional stability guarantees:

---

## Pre-1.0 Disclaimer
## Launch Window: MINOR Releases Can Contain Breaking Changes

<Callout type="warn">
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.
</Callout>

### 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 <before> <after> --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
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode");
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
docs(protocol): the pre-1.0 disclaimer's substance survived — restate it as the launch-window rule instead of deleting it#13895

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

os-project-manager
merged 2 commits into

from

Aug 31, 2026
 Merged


docs(protocol): the pre-1.0 disclaimer's substance survived — restate it as the launch-window rule instead of deleting it
#13895
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
ec82fc0

docs(protocol): restate the stale pre-1.0 disclaimer as the launch-wi…


claude Aug 31, 2026
a8c19e2

docs(changeset): declare the ADR-0087 disposition for the docs-only c…


claude Aug 31, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


51 changes: 51 additions & 0 deletions
.changeset/docs-backward-compat-launch-window.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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.

<!-- adr-0087: not-required (unpublished) The only bumped package is @objectstack/docs, which is `private: true` and absent from the Changesets `fixed` group, so nothing here reaches a published surface. This changeset removes, renames and narrows nothing; the BREAKING wording in the body quotes changelog entries that already shipped, and is not a breaking change declared by this diff. -->

22 changes: 20 additions & 2 deletions
content/docs/protocol/backward-compatibility.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -174,12 +174,30 @@ The `@objectstack/spec` package provides additional stability guarantees:

---

## Pre-1.0 Disclaimer
## Launch Window: MINOR Releases Can Contain Breaking Changes

<Callout type="warn">
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.
</Callout>

### 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 <before> <after> --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
Expand Down
Loading