Publish versioning, roadmap, and dependency policies for v2 - #3215
Publish versioning, roadmap, and dependency policies for v2#3215maxisbey wants to merge 4 commits into
Conversation
The versioning policy, roadmap, and dependency policy that the SEP-1730 tier assessment relies on were written to the v1.x branch and never came forward to main. Add them for v2 as they actually stand: a docs page stating the version scheme, the public-API boundary, what counts as breaking, and the two deprecation channels; a roadmap page pointing at the 2026-07-28 project board and the extension work still open; and a root DEPENDENCY_POLICY.md describing the floors-only requirement style and the automated-update setup. CONTRIBUTING.md gets the issue-triage section (label taxonomy, priority commitments) that its rewrite dropped, and RELEASE.md links the new dependency policy from the bump recipe. No-Verification-Needed: doc-only change
📚 Documentation preview
|
There was a problem hiding this comment.
All reported issues were addressed across 6 files
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
There was a problem hiding this comment.
Beyond the three inline findings, two candidate inconsistencies in the new CONTRIBUTING.md triage section were examined and ruled out: the status-label list omitting needs maintainer action (that label is discussed earlier in the file as a not-ready marker, not part of the shared status taxonomy the section documents), and the taxonomy differing from the labels the issue templates auto-apply (templates apply intake labels; the section describes the maintainer-applied taxonomy at triage time).
Extended reasoning...
This run found three nit-level wording/precision issues in the new policy docs, all posted as inline comments. Beyond those, finder agents raised two candidate contradictions in the CONTRIBUTING.md Issue Triage section, and I cross-checked them against the file and .github/ISSUE_TEMPLATE/: the templates auto-apply intake labels (question, v2, feature request, need confirmation) while the new section documents the shared maintainer-applied triage taxonomy, and the needs-maintainer-action mention is pre-existing text about work-readiness rather than the triage status set — so neither is a real inconsistency introduced by this PR. Recording this so a later pass does not re-explore the same candidates; it is informational only, not a correctness guarantee.
- versioning.md: name all three PEP 440 pre-release opt-in routes, matching RELEASE.md's wording. - versioning.md: say what a retired protocol feature does on each kind of connection instead of implying it keeps working everywhere. - roadmap.md: conformance runs on pull requests and pushes to main, not "every push". - RELEASE.md: the bump recipe said `uv lock --resolution lowest-direct`, which would floor the entire committed lock; the lock is a normal resolution and lowest-direct belongs only to the CI leg. No-Verification-Needed: doc-only change
There was a problem hiding this comment.
All reported issues were addressed across 3 files (changes from recent commits).
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
The second review round found the same class of problem as the first: the policy pages paraphrased behavior that other files own (deprecated features, pre-release selection, the CI matrix, SECURITY.md), and each paraphrase drifted from the code. Trim them back to the commitments and link to the owning page instead: - versioning.md: pre-release selection described by reference to PEP 440 rather than a closed list; provisional examples given as examples; the SDK-API deprecation promise stated as policy (marked wherever Python can carry a marker, docstring plus migration guide otherwise); protocol deprecations defer per-connection behavior to deprecated.md and legacy-clients.md instead of enumerating it. - roadmap.md: the open items are "carried as expected failures until they land", without tier-scoring commentary. - DEPENDENCY_POLICY.md: floors "the suite exercises" cannot go false; versioning.md is the single authority on release kinds; a dependency's new major is decided in an issue like a new dependency; SECURITY.md is a reporting process, not response commitments. - RELEASE.md: the lowest-direct lock is never committed (it is written, in CI's checkout); name the no-final-release pre-release fallback. - CONTRIBUTING.md: the label is `needs maintainer`. No-Verification-Needed: doc-only change
There was a problem hiding this comment.
Beyond the new inline finding, this run re-checked the earlier review threads against fbefbf6/e8bee4d: the RELEASE.md lock recipe (now plain uv lock), the pre-release opt-in wording, the deprecation-marker wording (module-level constants now carved out), the SECURITY.md pointer (softened to "reporting process"), and the cross-major floor-raise ambiguity (now an explicit maintainer decision) are all resolved as written. One earlier item is only partially addressed: the issue templates still apply need confirmation and feature request, which don't match the taxonomy CONTRIBUTING.md now publishes.
Extended reasoning...
Bugs were found this run (one nit: the SEP-2663 roadmap link 404s), so this is the informational ruled-out/progress note rather than a verdict. I verified in the checkout at HEAD that the five concerns raised in the 07-29 and 08-10 reviews were fixed by the two follow-up commits — several of those inline threads carry no resolved marker, so recording it here saves re-exploration. The remaining gap is the pre-existing issue-template labels (.github/ISSUE_TEMPLATE/bug.yaml: "need confirmation"; feature-request.yaml: "feature request") versus the taxonomy enumerated in CONTRIBUTING.md's new Issue Triage section. I am not approving: beyond the open nit, the PR publishes normative policy commitments (triage SLAs, the Python-EOL-in-a-minor rule, the message-text-is-not-API rule) that the description itself flags for maintainer judgment.
There was a problem hiding this comment.
2 issues found across 5 files (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="docs/versioning.md">
<violation number="1" location="docs/versioning.md:13">
P2: This sentence overstates pre-release opt-in behavior: installers can also pick a pre-release when no final release satisfies the specifier. Add that PEP 440 exception so this policy matches `RELEASE.md` and avoids misleading resolver expectations.</violation>
</file>
<file name="CONTRIBUTING.md">
<violation number="1" location="CONTRIBUTING.md:51">
P2: This line introduces a `needs maintainer` status label that is not part of the status taxonomy documented below, so contributors get conflicting guidance about which labels block work. Use a status label that exists in the taxonomy (for example `needs repro`) or update the taxonomy and label references consistently.</violation>
</file>
Tip: Review your code locally with the cubic CLI to iterate faster.
Re-trigger cubic
- roadmap.md: the SEP-2663 link pointed at a docs/seps/ path that 404s; SEPs live under seps/. Also "tracked as" rather than "exactly" for the baseline correspondence. - versioning.md: unpinned installs stay on stable "whenever one satisfies your requirement", which is the PEP 440 rule without a closed list. - DEPENDENCY_POLICY.md: extras hold add-on tooling; the transport stack and auth are base by design. The lowest-direct leg is described as what it does (tests floors continuously), not as a guarantee about every floor. - CONTRIBUTING.md: the taxonomy is the shared core; the repo also has workflow labels such as `needs maintainer`. No-Verification-Needed: doc-only change
There was a problem hiding this comment.
I reviewed the final revision (dfee3cb) and found no new issues — everything raised in my earlier passes is resolved, and the one deferred item (aligning the issue templates' labels: fields with the taxonomy) is reasonably split into a follow-up since it changes intake behavior. Because this PR publishes policy commitments (triage SLAs, the minor-release Python-drop rule, the support table) rather than describing existing behavior, maintainer sign-off is still the right final step.
What was reviewed this round:
- The dfee3cb fixes land as described: SEP-2663 link now under
seps/, taxonomy scoped as the shared core with repo workflow labels named, pre-release bullet states the PEP 440 rule itself. - Cross-checked factual claims against the repo:
mcp[cli]/mcp[rich]matchpyproject.toml's extras, andMCPDeprecationWarningis aUserWarningsubclass as the versioning page states. - All internal pages the two new docs link (
deprecated.md,run/legacy-clients.md,protocol-versions.md,whats-new.md,migration.md) exist in themkdocs.ymlnav.
Extended reasoning...
Overview
Docs/policy-only PR: two new docs pages (docs/versioning.md, docs/roadmap.md) added to the nav under a new About section, a new root DEPENDENCY_POLICY.md, an Issue Triage section in CONTRIBUTING.md, and small RELEASE.md wording updates. No code, no CI, no packaging changes. The PR went through three review rounds (mine and cubic's); the author addressed every finding across fbefbf6 and dfee3cb5.
Security risks
None operationally — no code paths change. The only security-adjacent content is documentation pointing security reports at SECURITY.md's private advisory channel, which is accurate in the final revision (the earlier over-claim about "response commitments" was fixed).
Level of scrutiny
The text itself got heavy scrutiny across three rounds and the final revision is internally consistent and factually accurate against the repo (extras names, MCPDeprecationWarning semantics, linked pages, external SEP link). But the substance is a set of public commitments the maintainers are making — a two-business-day triage SLA, P0 resolved within 7 days, dropping EOL Python versions in a minor release (explicitly reversing the v1.x stance), and the public-API boundary definition. Whether the team wants to be bound by those is a governance decision, not a correctness question, so this should not be shadow-approved regardless of textual quality.
Other factors
The bug hunting system found no issues this run. All prior inline threads are resolved; the issue-template label alignment is deliberately deferred to a follow-up PR, which I verified is still outstanding in the checkout (.github/ISSUE_TEMPLATE/bug.yaml still applies need confirmation) but is out of scope here by the author's stated intent. The docs build and markdownlint are reported green by the author.
The versioning policy, roadmap, and dependency policy that the SEP-1730 tier assessment relies on were written to
v1.x(#2084) after the branches diverged and never came forward, so the default branch has been without them since v2 became the default. Rather than port them — v1.x's roadmap links the TypeScript project board and dates v2 as "alpha ~mid-March", and its versioning doc describes a release model that no longer exists — this writes them for v2 as it actually stands.Motivation and Context
docs/versioning.md("Versioning and support policy") — SemVer semantics in PEP 440 syntax,mcp/mcp-typeslockstep, the public-API boundary (__all__plus documented paths; message text is not API), what is and is not a breaking change, provisional/experimental as the two carve-outs, and the two deprecation channels (@deprecatedfor SDK APIs,MCPDeprecationWarningfor spec-retired features). LinksSECURITY.mdfor the supported-lines table.docs/roadmap.md— organized by spec revision: the 2026-07-28 project board (Types Rework #42) and its one open item (Capabilities API + server/discover handler #2896), then the not-yet-implemented set, which is exactly the conformance expected-failures baseline — the tasks extension (SEP-2663, Implement SEP-2663: Tasks Extension #2806), DPoP (SEP-1932), and thejwt-bearergrant — plus the v1.x maintenance stance.DEPENDENCY_POLICY.md(root, sincedocs/dependency-policy.mdis the only docs path the tier check reads and it isn't a natural nav page) — floors-only requirements, themcp-typesexact pin explained, why floors don't move for CVEs (theAGENTS.mdstance, with the uvicorn and mitigate CVE-2025-62727 for starlette #1552 reasoning linked), the lowest-direct CI leg that keeps floors honest, and the Dependabot uv/actions setup.CONTRIBUTING.md— an "Issue Triage" section (two-business-day first label, the shared taxonomy, P0 = resolved within 7 days) — the SLA text SEP-1730 measures, which the rewrite had dropped — and a pointer to the dependency policy.RELEASE.md's bump recipe links it too.Two policy statements in the versioning page are worth an explicit look, since they are commitments rather than descriptions:
How Has This Been Tested?
scripts/docs/build.sh(strict Zensical build + cross-reference check) green with the two new pages in the nav; markdownlint clean.Breaking Changes
None.
Types of changes
Checklist
Additional context
Deliberately not in this PR: the feature-documentation gaps against the tier audit's 48-feature list (a docs PR of their own), the v1.x roadmap's stale content, and a CHANGELOG.md (GitHub Releases remain the changelog, as on every other SDK).
AI Disclaimer