[Docs] Deprecation policy, SDK tier target, and CONTRIBUTING.md (#472)
* [Docs] Add deprecation policy doc (SEP-2596) Formalizes the Active -> Deprecated -> Removed lifecycle and the twelve-month deprecation window the SDK already applies via SEP-2577, and states the SDK's own BC promise ahead of 1.0. * [Docs] Add SDK Tier 2 gap analysis (SEP-1730) * [Docs] Wire deprecation policy and SDK tier docs into the guide nav Adds both pages under a new Project section in mkdocs.yml, links them from index.md's "Where to go next", and points their repo-root references at GitHub URLs instead of paths escaping docs/ (dead under Zensical's --strict build). * [Docs] Add CONTRIBUTING.md Root-level contribution guide: dev setup, the make ci checks to run before a PR, coding standards, testing expectations, the docs-guide link-resolution rule Zensical enforces, and licensing terms. Linked from README's existing Contributing section. * [Docs] Trim deprecation policy per review Drop the worked SEP-2577 example and the "relationship to the protocol lifecycle" section; both were redundant restating of detail that lives in the code/CHANGELOG and protocol-versions.md already. * [Docs] Cite the Tier 3 audit and add a versioning policy (SEP-1730) Replace our own hand-rolled conformance numbers with the authoritative audit in modelcontextprotocol/modelcontextprotocol#3274: SDK is currently Tier 3, blocked from Tier 2 by client OAuth conformance (20%) and no stable 1.0.0+ release. Add the Versioning section the audit found missing — SemVer commitment pre-1.0, Symfony's BC promise after — and point CONTRIBUTING.md at it. * [Docs] Link Symfony's BC promise from the deprecation policy Was plain text; sdk-tier.md's Versioning section already links it. * [Docs] Drop the "process gaps addressed" aside from sdk-tier.md * Apply suggestion from @chr-hertel * Apply suggestion from @chr-hertel
This commit is contained in:
Christopher Hertel
GitHub
parent
d09fe3019e
commit
1e9520e731
3 changed files with 189 additions and 1 deletions
28
docs/deprecation-policy.md
Normal file
28
docs/deprecation-policy.md
Normal file
|
|
@ -0,0 +1,28 @@
|
|||
# Deprecation policy
|
||||
|
||||
The MCP specification (SEP-2596) defines a formal feature lifecycle: **Active → Deprecated → Removed**,
|
||||
with a minimum of twelve months between a feature being marked deprecated and its earliest possible removal.
|
||||
Each stage transition gets its own SEP — deprecating a feature and removing it are separate proposals, never
|
||||
bundled into one.
|
||||
|
||||
The PHP SDK mirrors that window for anything it deprecates, whether the deprecation originates in the spec
|
||||
or is SDK-internal (an API shape the SDK wants to retire independently of the protocol).
|
||||
|
||||
## What a deprecation looks like here
|
||||
|
||||
A deprecated element carries a PHP `@deprecated` tag naming the protocol revision (or SDK version, for an
|
||||
SDK-internal deprecation) that introduced the deprecation and the earliest removal date, twelve months out:
|
||||
|
||||
```php
|
||||
/**
|
||||
* @deprecated since protocol revision 2026-07-28 (SEP-2577), earliest removal 2027-07-28.
|
||||
*/
|
||||
```
|
||||
|
||||
## The SDK's own BC promise
|
||||
|
||||
The SDK is pre-1.0 and experimental, and the public
|
||||
API can still change without a deprecation cycle where the spec itself hasn't moved. Once past 1.0, the SDK
|
||||
follows [Symfony's backward-compatibility promise](https://symfony.com/doc/current/contributing/code/bc.html),
|
||||
and the twelve-month deprecation window above becomes the
|
||||
floor for any BC break the SDK introduces on its own, not just ones the spec forces.
|
||||
|
|
@ -97,6 +97,9 @@ around in.
|
|||
**[Clients](client/index.md)**.
|
||||
* The two protocol eras, and what revision `2026-07-28` changed, are
|
||||
**[Protocol versions](protocol-versions.md)**.
|
||||
* What gets deprecated, for how long, and where the SDK stands on spec-tier
|
||||
support are under **Project**: **[Deprecation policy](deprecation-policy.md)**
|
||||
and **[SDK tier target](sdk-tier.md)**.
|
||||
* Complete, runnable projects are in **[Examples](examples.md)**.
|
||||
* Hunting for an exact signature? The **[API Reference](https://php.sdk.modelcontextprotocol.io/api/)**
|
||||
is generated from the source.
|
||||
|
|
|
|||
68
docs/sdk-tier.md
Normal file
68
docs/sdk-tier.md
Normal file
|
|
@ -0,0 +1,68 @@
|
|||
# SDK Tier Target (SEP-1730)
|
||||
|
||||
The MCP spec defines three SDK tiers: Tier 1 (Fully Supported), Tier 2
|
||||
(Commitment to Full Support), and Tier 3 (Experimental). This document tracks
|
||||
where the PHP SDK stands and what's still missing to move up a tier.
|
||||
|
||||
## Current standing
|
||||
|
||||
**Tier 3**, per the official audit in
|
||||
[modelcontextprotocol/modelcontextprotocol#3274](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/3274)
|
||||
(2026-08-19, superseding the earlier Tier 3 assessment in #2305). Two things
|
||||
block Tier 2:
|
||||
|
||||
- **Client conformance is 20% (10/50)**, against the ≥80% bar. Almost
|
||||
entirely OAuth: 38 of 39 scored auth scenarios fail. Every one of those
|
||||
failures is pre-declared in the SDK's own
|
||||
[`tests/Conformance/conformance-baseline-*.yml`](https://github.com/modelcontextprotocol/php-sdk/tree/main/tests/Conformance)
|
||||
files and tracked in `ROADMAP.md` — a known, scoped gap, not silent
|
||||
breakage. Server conformance is 100% (67/67).
|
||||
- **No stable release ≥ 1.0.0 has ever shipped** (latest: v0.7.1). Tier 2
|
||||
requires at least one.
|
||||
|
||||
Tier 1 needs both of those plus full (not ≥80%) client conformance and
|
||||
closing 10 documentation gaps the audit lists by name (mostly small
|
||||
per-feature additions — legacy SSE transport and the elicitation
|
||||
complete-notification need either an implementation or an explicit
|
||||
"intentionally not implemented" note).
|
||||
|
||||
## Target
|
||||
|
||||
**Tier 2 next, Tier 1 after the 1.0 release.** Tier 1's "stable release"
|
||||
requirement is structurally out of reach until 1.0 ships regardless of how
|
||||
complete every other Tier 1 criterion is.
|
||||
|
||||
## Path to Tier 2
|
||||
|
||||
Roughly in priority order, per the audit's own recommendation:
|
||||
|
||||
1. **OAuth client conformance.** The single highest-leverage fix — it
|
||||
accounts for 38 of 40 client failures and blocks both tiers on its own.
|
||||
Already scoped: token endpoint auth methods, scope handling (step-up,
|
||||
retry-limit, from-`WWW-Authenticate`, from `scopes_supported`), dynamic
|
||||
client registration, issuer validation, `offline_access`,
|
||||
authorization-server migration — see `ROADMAP.md` and the
|
||||
`2026-07-28`-labeled auth issues.
|
||||
2. **Fix the two non-auth client failures** (`sse-retry`,
|
||||
`elicitation-sep1034-client-defaults`, both scored at 2025-11-25).
|
||||
3. **Ship a stable 1.0.0+ release.**
|
||||
|
||||
## Versioning
|
||||
|
||||
The SDK follows [Semantic Versioning](https://semver.org/):
|
||||
`MAJOR.MINOR.PATCH`. Pre-1.0, that means any digit can carry a breaking
|
||||
change per SemVer §4 — every one is logged with a `[BC Break]` marker in
|
||||
[`CHANGELOG.md`](https://github.com/modelcontextprotocol/php-sdk/blob/main/CHANGELOG.md).
|
||||
|
||||
Once at 1.0, the SDK adopts Symfony's
|
||||
[Backward Compatibility Promise](https://symfony.com/doc/current/contributing/code/bc.html):
|
||||
PATCH releases never break BC, MINOR releases only add functionality (gated
|
||||
by the deprecation window in [Deprecation policy](deprecation-policy.md)),
|
||||
and a breaking change ships only in a MAJOR release.
|
||||
|
||||
## Roadmap
|
||||
|
||||
See [ROADMAP.md](https://github.com/modelcontextprotocol/php-sdk/blob/main/ROADMAP.md)
|
||||
for the feature-level plan toward 1.0. This document only tracks the
|
||||
process/tier-classification gap, which is narrower and more mechanical than
|
||||
the feature roadmap.
|
||||
Loading…
Reference in a new issue