1e9520e731* [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
1.3 KiB
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:
/**
* @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, 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.