Repository navigation
Conversation
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>
bokelley
force-pushed
the
docs/dr-4x-evolution-contract
branch
from
November 12, 2026 16:17
a42753a to
44d8661
Compare
KonstantinMirin
left a comment
Collaborator
There was a problem hiding this comment.
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 holdsproposal-budget-constraintwith 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-termsas 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-termsand the term objects inside it, andproposal-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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
x-closed-reason, and CI checks it. When one field must stay forbidden on an open schema, the schema names it withnot: { anyOf: [{ required }] }.deprecated: truenode carriesx-deprecated-in, plus eitherx-removed-inorx-retained. The lint reads those fields, not the prose.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 inversioning.mdx(docs(governance): DR-0036 records open schemas within a major; withdraw DR-0032 and DR-0033 #8858, merged).The record also lists the alternatives considered and why each was rejected.
Decided since the first draft
versioning.mdx. The 6-or-12 placeholder and conflict note are gone.Not in this PR
versioning.mdx,specification-lifecycle.mdxandexperimental-status.mdx. On ratification,versioning.mdxadds corrections to its security-only support promise andexperimental-status.mdxadds the clock, as the record's Implications list says.x-closed-reasonand clock checks, and the baseline reset are 4.0 work.governance/is outside protocol scope.Related PRs
versioning.mdx. This branch is rebased onto it.Checks
dissentvalue is quoted because it contains#.scripts/lint-decision-record-status.cjsfrom fix(governance): mark six WG-ratified decision records ratified and lint record status #8819 passes this record. Its six errors onmainare in existing records withstatus: accepted, and fix(governance): mark six WG-ratified decision records ratified and lint record status #8819 fixes them.--no-verify). It changes one Markdown file undergovernance/, which no unit suite or typecheck covers.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