docs(dev-docs): Document the spec lifecycle and maturity framework#18275
docs(dev-docs): Document the spec lifecycle and maturity framework#18275chargome wants to merge 4 commits into
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit 2dfe814. Configure here.
| ### draft → candidate | ||
|
|
||
| - There **MUST** be at least **one** SDK implementation demonstrating the spec is feasible as written. | ||
| - The spec version **MUST** be bumped to `1.0.0` (see [Version semantics](#version-semantics)). |
There was a problem hiding this comment.
Section rules conflict versioning
Medium Severity
Per-section promotion is bound to the full draft → candidate checklist, including a spec_version of 1.0.0, while draft specs must remain 0.x and sections may mature independently. A section cannot move to candidate under those rules without contradicting draft versioning or independent section advancement.
Additional Locations (2)
Reviewed by Cursor Bugbot for commit 2dfe814. Configure here.
|
|
||
| - There **SHOULD** be at least **two** independent, interoperable SDK implementations of each feature — the signal that the spec is implementable consistently across SDKs, not just in the one that shaped it. | ||
| - Where two implementations don't yet exist, the gap **SHOULD** be recorded (in the changelog summary or an open-questions note) rather than silently promoted. | ||
| - No breaking changes **SHOULD** remain outstanding. |
There was a problem hiding this comment.
"There SHOULD be at least two independent, interoperable SDK implementations" could be read as a gate on promotion (you need two before promoting), but I think the intent was that there MUST be at least one (from the draft → candidate gate) and a second is preferable?
A small rewording could make the intent clearer. Something like:
- A second independent SDK implementation SHOULD exist to confirm the spec is
implementable consistently across SDKs, not just in the one that shaped it. - If only one implementation exists at promotion time, the gap MUST be recorded
in the changelog summary or an open-questions note.
I would use MUST on the second bullet point to strengthen the transition criteria
dingsdax
left a comment
dingsdax
left a comment
There was a problem hiding this comment.
one small comment for the candidate → stable gate, otherwise big ❤️
Love the W3C alignment and the clearly defined transition criteria.
It describes very well the "implementation/evidence promotion model" that SDKs have been following implicitly anyways (more or less). Great to see that codified now 👏 and hopefully even better prevents any future specs from drifting into aspirational territory 😅. Good stuff!
2 participants
Adds a meta-spec documenting the SDK spec lifecycle framework, which until now existed only in code (
specConstants.ts) with no written definition of what each status means or when a spec may advance.The new page defines the status model (proposal, draft, candidate, stable, deprecated), the frontmatter/section structure, version semantics, and—most importantly—the implementation-based promotion criteria between statuses, aligned with the W3C Process maturity stages.
ref #16461