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
28 lines
1.3 KiB
Markdown
28 lines
1.3 KiB
Markdown
# 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.
|