Skip to content

Commit 4485f7d

Browse files
claude[bot]claude
andauthored
docs(protocol): drop phantom labels and unbacked promises from the backward-compatibility page (#14385)
- Breaking Change Process step 1: point at the label that actually exists, `protocol:breaking`, instead of the never-created `breaking-change`. - Reporting Compatibility Issues step 2: drop the `compatibility` label instruction entirely — no reader exists for it, so it does not exist either. - Delete the unsourced "minimum 2 MINOR releases" deprecation-survival guarantee (heading, mermaid diagram, and callout) and state the true process instead: a deprecated feature is retired at the boundary the ADR-0087 registry records for it, with no minimum dwell time. - Re-derive the "tracked separately and deliberately not stated here" sentence: the launch window closes at GA and strict SemVer resumes from that point, per `scripts/check-changeset-no-major.mjs`'s own end-condition header. _Generated by [Claude Code](https://claude.ai/code/session_01WLJQhde67SeTccsmnBVarV)_ Co-authored-by: Claude <noreply@anthropic.com>
1 parent f7d92d3 commit 4485f7d

1 file changed

Lines changed: 7 additions & 8 deletions

File tree

content/docs/protocol/backward-compatibility.mdx

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ When a feature, schema property, or API is deprecated, ObjectStack follows a str
5555
- Runtime warning is emitted on first use (once per session)
5656
- Migration path is documented in the CHANGELOG
5757

58-
### Phase 2: Migration Period (minimum 2 MINOR releases)
58+
### Phase 2: Migration Period
5959

6060
- Deprecated feature continues to function without behavior changes
6161
- Documentation is updated with migration guides
@@ -75,13 +75,12 @@ Shipped examples: `17.2.0` retired `http_request_errors_total` and `sys_position
7575

7676
```mermaid
7777
flowchart TD
78-
A["v3.2.0 — feature deprecated (warning emitted)"] --> B["v3.3.0 — migration period continues"]
79-
B --> C["v3.4.0 — migration continues (minimum 2 minor releases)"]
80-
C --> D["v3.5.0 — feature removed (earliest possible removal, MINOR)"]
78+
A["Deprecation notice — feature marked deprecated (warning emitted)"] --> B["Migration period — deprecated feature keeps working, no behavior change"]
79+
B --> C["Removal — retired at the boundary the ADR-0087 registry records (MINOR release, during the launch window)"]
8180
```
8281

8382
<Callout type="warn">
84-
**Minimum guarantee:** Deprecated features survive for at least **2 MINOR releases** before they can be removed. During the launch window the removal itself lands in a MINOR release, so a MINOR bump is where you should expect a removal to arrive.
83+
**No minimum survival window.** ObjectStack does not guarantee a deprecated feature survives for a fixed number of releases[ADR-0049](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0049-no-unenforced-security-properties.md)'s dispositions for a flagged property are enforce, `experimental`, or remove, and none of them carries a dwell time. A deprecated feature is retired at the boundary the ADR-0087 registry records for it; during the launch window that removal itself lands in a MINOR release, so a MINOR bump is where you should expect a removal to arrive.
8584
</Callout>
8685

8786
---
@@ -109,7 +108,7 @@ Read the **Breaking?** column, not the version number: during the launch window
109108

110109
### Breaking Change Process
111110

112-
1. **RFC (Request for Comments)** — Breaking changes are proposed as GitHub issues with the `breaking-change` label.
111+
1. **RFC (Request for Comments)** — Breaking changes are proposed as GitHub issues with the `protocol:breaking` label.
113112
2. **Deprecation** — The old behavior is deprecated in a MINOR release (see timeline above).
114113
3. **Migration Guide** — A detailed migration guide is published before the removal lands, in the release notes for the version that carries it.
115114
4. **Release** — During the launch window the breaking change ships in the next **MINOR** version, carrying a changeset entry marked `**BREAKING**`. `scripts/check-changeset-no-major.mjs` fails any pull request that declares a `major` bump, because under lockstep one `major` would promote all 69 published packages.
@@ -204,7 +203,7 @@ MAJOR releases do still happen — 17.0.0 was cut precisely because its breaking
204203

205204
### When it stops applying
206205

207-
The tables and deprecation timeline above now state this rule directly, so the page no longer contradicts itself. Classic SemVer — where a breaking change once again requires a MAJOR — is the settled form the project returns to once the launch window closes; the condition that closes the window is tracked separately and is deliberately not stated here. Until it closes, **this section is the operative rule wherever any part of this page disagrees.**
206+
The tables and deprecation timeline above now state this rule directly, so the page no longer contradicts itself. Classic SemVer — where a breaking change once again requires a MAJOR — is the settled form the project returns to once the launch window closes: the window closes at GA, and strict SemVer resumes from that point. Until it closes, **this section is the operative rule wherever any part of this page disagrees.**
208207

209208
---
210209

@@ -213,6 +212,6 @@ The tables and deprecation timeline above now state this rule directly, so the p
213212
If you encounter an unintended breaking change:
214213

215214
1. **Check the CHANGELOG** — Verify the change was not documented as intentional.
216-
2. **Open an issue** — File a GitHub issue with the `compatibility` label.
215+
2. **Open an issue** — File a GitHub issue describing the unintended change.
217216
3. **Include a reproduction** — Provide a minimal code sample showing the breakage.
218217
4. **Reference the version** — Specify the exact versions where behavior changed.

0 commit comments

Comments
 (0)