Skip to content

docs(governance): propose DR-0039, the 4.x evolution contract - #8881

Draft
bokelley wants to merge 4 commits into
mainfrom
docs/dr-4x-evolution-contract
Draft

bokelley wants to merge 4 commits into
mainfrom
docs/dr-4x-evolution-contract

Conversation

@bokelley

@bokelley bokelley commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

This adds DR-0039 with status proposed. It is the decision record for theme T3 of RFC #8756: the evolution contract for every 4.x release. It records no decision date or authority, because it isn't operative yet. Comments on #8756 close Dec 4, and scope freezes Dec 18. Ratification changes the status and adds the provenance. The PR stays a draft until the RFC comment period ends.

What the record settles

  1. The four rules of docs(versioning): state the rules for what changes between releases #8704 govern 4.x. Rule 4's exception is in the record: a field that changes what a seller commits to can ship in a minor behind a capability the seller declares first. A buyer MUST NOT send it to a seller that doesn't declare the capability. The additive-minor check runs from 4.0.0 GA with an empty baseline and an empty corrections register. A 4.x baseline entry needs a ratified record; "pending WG decision" doesn't qualify.
  2. Schemas are open by default. DR-0036 (rewritten in docs(governance): DR-0036 records open schemas within a major; withdraw DR-0032 and DR-0033 #8858, merged) holds in 4.x. A schema closes only for a reason from a fixed list: the reasons fix(schemas): open the 3.3 schemas that were meant to be open #8866 (merged) approved for 3.3, grouped as eight. A table maps fix(schemas): open the 3.3 schemas that were meant to be open #8866's eleven reasons (115 locations) onto the eight, and the WG can split them back. Each closed node names its reason in x-closed-reason, and CI checks it. When one field must stay forbidden on an open schema, the schema names it with not: { anyOf: [{ required }] }.
  3. Deprecation is machine-readable. Every deprecated: true node carries x-deprecated-in, plus either x-removed-in or x-retained. The lint reads those fields, not the prose.
  4. Removal and support (Brian, 2026-11-10). A major may remove anything deprecated in an earlier release, with no minimum notice. Implementers are protected by the support window of the previous major's last minor: 3.3 for 4.0, for at least 12 months after the successor's GA, matching the published versioning.mdx. "Supported" means security fixes plus corrections, which widens today's security-only promise. This replaces the minimum 6 months' deprecation notice. That rule and the 12-month window are already in versioning.mdx (docs(governance): DR-0036 records open schemas within a major; withdraw DR-0032 and DR-0033 #8858, merged).
  5. Experimental surfaces get a clock of four minors. Each surface graduates or leaves within four minors. Surfaces carried into 4.0.0 start their clock there, so their deadline is 4.4. The WG can extend one surface's clock once, by up to two minors. The 6-week notice still applies within a major. The record gives the reasoning for four.
  6. Served-release conformance (DR-0024) carries into 4.x unchanged.

The record also lists the alternatives considered and why each was rejected.

Decided since the first draft

Not in this PR

  • No docs change. docs(governance): DR-0036 records open schemas within a major; withdraw DR-0032 and DR-0033 #8858 (merged) already removed the 6-month deprecation notice from versioning.mdx, specification-lifecycle.mdx and experimental-status.mdx. On ratification, versioning.mdx adds corrections to its security-only support promise and experimental-status.mdx adds the clock, as the record's Implications list says.
  • No tooling. The deprecation-field lint, the x-closed-reason and clock checks, and the baseline reset are 4.0 work.
  • No changeset. governance/ is outside protocol scope.

Related PRs

Checks

governance/** is Ladon-gated, so a human merges this. It stays a draft until the RFC comment period closes on Dec 4.

🤖 Generated with Claude Code

bokelley and others added 4 commits November 12, 2026 16:16
Draft of theme T3 of RFC #8756 as a proposed decision record. It covers
the #8704 rules for 4.x, including the rule 4 capability exception, and
the additive-minor check from 4.0.0 with an empty baseline. It sets a
fixed list of structural reasons for closing a schema, with named
rejections. It makes deprecation dispositions machine-readable. It
allows removal in a major with no minimum notice, protected by the
previous major's support window, with N pending. It puts a four-minor
clock on experimental surfaces and carries DR-0024 unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ort promise in DR-0039

Add a table that maps the eleven reasons #8866 gives for 3.3's closed
locations onto the record's eight, and note that the WG can split them
back. State that "supported" (security fixes plus corrections) widens
the versioning page's security-only promise. Drop the 4.0 GA-date
reasoning, which RFC #8756 carries.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nths

Brian ruled that the last minor of the previous major stays supported
for at least 12 months after the successor's GA, which matches the
published versioning page. Drop the 6-or-12 conflict note and the
conditional DR-0007 supersession. Cite PR #8858 for removing the
6-month deprecation notice instead of listing it as a future doc change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
#8858 is merged, so the versioning page already states the
no-minimum-notice removal rule and the 12-month support window. Point
DR-0039 at versioning.mdx (#8858, merged) instead of a pending PR.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@bokelley
bokelley force-pushed the docs/dr-4x-evolution-contract branch from a42753a to 44d8661 Compare November 12, 2026 16:17

@KonstantinMirin KonstantinMirin left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for writing the 4.x contract down. One point on the reason table: DR-0039 keeps signed commercial terms as a structural reason, while the 3.3 pages on main call them a hold.

  • On main, the 3.3 migration guide says the commercial terms are "held closed until 4.0" and "This is a hold, not a structural reason" (3-2-to-3-3.mdx:397), and holds proposal-budget-constraint with them (:401). #8866's table labels the same 26 locations "Held closed until 4.0 (commercial terms)", and your #8884 review describes #8866 that way.
  • DR-0036, as merged, still lists "A signed or binding payload" as a structural reason, with commercial-terms as the example (:30-32, rationale at :90-91). DR-0039 carries it into 4.x as "Signed or digest-bound terms" (:56) and maps those 26 locations onto it (:71-72).

With the rule you approved on #8884, a signed payload no longer needs closure. terms_digest covers every member at every depth, accepting binds a party to all of them, and a party that can't interpret a member refuses. That holds whether the schema is open or closed. So closing these schemas is a hold until 4.0, and 4.x doesn't need it as a reason. proposal-budget-constraint isn't signed, but the 3.3 pages hold it with the terms, so it moves with them.

Could DR-0039 list it that way? A possible change:

  • Drop the "Signed or digest-bound terms" row, so "grouped as eight" becomes seven (:50-51).
  • After the mapping table: "Held closed until 4.0, as a hold and not a structural reason: commercial-terms and the term objects inside it, and proposal-budget-constraint (#8866). In 4.x, the #8884 rule covers signed terms." How they grow in 4.0 stays under "Not settled here".
  • The two mapping rows at :71-72 read "Hold until 4.0" instead of a 4.x reason.
  • DR-0036's third reason and its rationale sentence change the same way, here or in a small follow-up, so the merged record matches the 3.3 pages.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants