From 11fb039bcc7ca52c27f8c8aaeb2c92cdf1075bcd Mon Sep 17 00:00:00 2001 From: Christopher Hertel Date: Wed, 19 Aug 2026 03:40:15 +0200 Subject: [PATCH 1/8] [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/deprecation-policy.md | 45 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 docs/deprecation-policy.md diff --git a/docs/deprecation-policy.md b/docs/deprecation-policy.md new file mode 100644 index 00000000..70365f37 --- /dev/null +++ b/docs/deprecation-policy.md @@ -0,0 +1,45 @@ +# 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. + */ +``` + +This is already in place for the first real instance of the policy: SEP-2577 deprecated Roots, Sampling and +Logging in the `2026-07-28` revision (merged in #427). Twenty-seven call sites across `src/Schema/`, +`src/Client/` and `src/Server/` carry the tag today — see `RootsListChangedNotification`, +`SetLogLevelRequest`, `LoggingMessageNotification`, `SamplingCallbackInterface`, and others. Each keeps +working exactly as before; the tag is a migration signal, not a behavior change. The CHANGELOG entry for +that release states the same window and points at the replacement for each: tool arguments or resource URIs +instead of roots, a direct LLM provider integration instead of sampling, `stderr`/OpenTelemetry instead of +`notifications/message`. + +## The SDK's own BC promise + +The SDK is pre-1.0 and experimental — the root `README.md` and `CLAUDE.md` say so plainly, 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. + +## Relationship to the protocol lifecycle + +This document covers deprecation as an API-surface concern: what gets tagged, for how long, with what +migration note. It's a different (related) axis from +[protocol era support](stateless-lifecycle.md#what-was-removed) — which protocol revisions the SDK serves at +all, and what a given revision no longer accepts on the wire. A method can be removed from the modern +revision's wire surface while its PHP binding stays present and undeprecated, because a handshake-era client +still needs it; see the stateless lifecycle guide's "What was removed" section for the current list. From 961647dfea56e5c0b9bf9824496377751b355964 Mon Sep 17 00:00:00 2001 From: Christopher Hertel Date: Wed, 19 Aug 2026 03:40:30 +0200 Subject: [PATCH 2/8] [Docs] Add SDK Tier 2 gap analysis (SEP-1730) --- docs/sdk-tier.md | 58 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 docs/sdk-tier.md diff --git a/docs/sdk-tier.md b/docs/sdk-tier.md new file mode 100644 index 00000000..4321a58d --- /dev/null +++ b/docs/sdk-tier.md @@ -0,0 +1,58 @@ +# 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 against the Tier 2 bar and what's still missing. + +## Target + +**Tier 2 now, Tier 1 after the 1.0 release.** + +Tier 1 requires a stable release with clear versioning. The SDK is currently +pre-1.0 and experimental (see [CLAUDE.md](../CLAUDE.md)), so Tier 1 is +structurally out of reach until 1.0 ships regardless of how complete any +other Tier 1 criterion is. Tier 2 has no such blocker and is achievable now. + +## Gap analysis against Tier 2 + +| Requirement | Status | Evidence | +|---|---|---| +| ≥80% conformance | **Gap — server yes, client no** | Server: 144/145 (99%) on 2026-07-28, 39/40 (98%) on 2025-11-25. Client: 16/80 (20%) on 2026-07-28, 2/44 (5%) on 2025-11-25. The SDK is strong on the server surface and far below the bar on the client surface. This is the single largest gap to Tier 2 — closing it means building out client-side conformance coverage, not just docs/process. | +| New features within 6 months of a spec release | Informal, not tracked | No published SLA. The `2026-07-28`-labeled issue set and this triage effort are the closest thing to a tracked adoption process today; nothing publishes a commitment. | +| Triage within a month | Informal, not tracked | No published triage SLA. Labels exist to support one (see below) but aren't backed by a stated commitment. | +| P0 fix ≤2 weeks | Informal, not tracked | `P0`–`P3` labels exist and are used, but no published response-time commitment. | +| ≥1 stable release | Not yet | SDK is pre-1.0. | +| Basic docs | **Met** | `docs/` covers the builder API, client, transports, elements, events, authorization, extensions, and the stateless lifecycle. | +| Standardized GitHub label set | **Met** | `bug`, `enhancement`, `question`, `needs confirmation`, `needs repro`, `ready for work`, `good first issue`, `help wanted`, `P0`–`P3` are all present and in active use (confirmed via `gh label list`). | +| Published dependency-update policy | **Gap — mechanism exists, not documented** | `make deps-stable` / `make deps-low` (wired into `ci-stable` / `ci-lowest`) already test against both the newest and lowest-compatible dependency sets on every CI run. There's no doc stating this as a policy or naming a support window. | + +## What closes the gap + +Roughly in priority order: + +1. **Client conformance.** This is the real blocker, not a doc gap. The + client suite is failing the large majority of scenarios (20% / 5%). + Investigate what's actually failing before assuming it's missing + features vs. test/harness gaps — either way this needs engineering work, + tracked separately from this doc. +2. **Publish the dependency-update policy.** The mechanism (`deps-stable`, + `deps-low` in CI) already enforces support for both the newest and the + lowest compatible dependency versions on every run. What's missing is a + short published statement saying so, so it counts as "published" rather + than merely "true." That's a stated policy, not new code: + > The SDK's `composer.json` constraints are tested on every CI run + > against both the newest allowed versions (`make deps-stable`) and the + > lowest allowed versions (`make deps-low`), so both ends of the declared + > range are guaranteed to work. Dependency bumps land as regular PRs; + > there's no separate deprecation/removal schedule for dependencies + > beyond what `composer.json`'s version constraints already express. +3. **State the triage/response SLAs**, once the team is actually willing to + commit to the Tier 2 numbers (triage within a month, P0 fix within two + weeks). Labels already exist to support this; only the commitment itself + is missing, and it isn't this document's call to make. + +## Roadmap + +See [ROADMAP.md](../ROADMAP.md) for the feature-level plan toward 1.0. This +document only tracks the process/tier-classification gap, which is a +narrower and more mechanical thing than the feature roadmap. From febe648669d7078151bd19ece15331fe926846dd Mon Sep 17 00:00:00 2001 From: Christopher Hertel Date: Sat, 22 Aug 2026 02:09:01 +0200 Subject: [PATCH 3/8] [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/deprecation-policy.md | 5 +++-- docs/index.md | 3 +++ docs/sdk-tier.md | 15 +++++++++------ mkdocs.yml | 3 +++ 4 files changed, 18 insertions(+), 8 deletions(-) diff --git a/docs/deprecation-policy.md b/docs/deprecation-policy.md index 70365f37..bd391219 100644 --- a/docs/deprecation-policy.md +++ b/docs/deprecation-policy.md @@ -39,7 +39,8 @@ floor for any BC break the SDK introduces on its own, not just ones the spec for This document covers deprecation as an API-surface concern: what gets tagged, for how long, with what migration note. It's a different (related) axis from -[protocol era support](stateless-lifecycle.md#what-was-removed) — which protocol revisions the SDK serves at +[protocol era support](protocol-versions.md#what-was-removed) — which protocol revisions the SDK serves at all, and what a given revision no longer accepts on the wire. A method can be removed from the modern revision's wire surface while its PHP binding stays present and undeprecated, because a handshake-era client -still needs it; see the stateless lifecycle guide's "What was removed" section for the current list. +still needs it; see [Protocol versions](protocol-versions.md)' "What was removed" and "Deprecations" +sections for the current list. diff --git a/docs/index.md b/docs/index.md index cc9c375a..4b31a92c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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. diff --git a/docs/sdk-tier.md b/docs/sdk-tier.md index 4321a58d..a7aca28b 100644 --- a/docs/sdk-tier.md +++ b/docs/sdk-tier.md @@ -9,9 +9,11 @@ where the PHP SDK stands against the Tier 2 bar and what's still missing. **Tier 2 now, Tier 1 after the 1.0 release.** Tier 1 requires a stable release with clear versioning. The SDK is currently -pre-1.0 and experimental (see [CLAUDE.md](../CLAUDE.md)), so Tier 1 is -structurally out of reach until 1.0 ships regardless of how complete any -other Tier 1 criterion is. Tier 2 has no such blocker and is achievable now. +pre-1.0 and experimental (see +[CLAUDE.md](https://github.com/modelcontextprotocol/php-sdk/blob/main/CLAUDE.md)), +so Tier 1 is structurally out of reach until 1.0 ships regardless of how +complete any other Tier 1 criterion is. Tier 2 has no such blocker and is +achievable now. ## Gap analysis against Tier 2 @@ -53,6 +55,7 @@ Roughly in priority order: ## Roadmap -See [ROADMAP.md](../ROADMAP.md) for the feature-level plan toward 1.0. This -document only tracks the process/tier-classification gap, which is a -narrower and more mechanical thing than the feature 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 a narrower and more mechanical +thing than the feature roadmap. diff --git a/mkdocs.yml b/mkdocs.yml index 491441b4..d5e45434 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -54,6 +54,9 @@ nav: - Events: advanced/events.md - Protocol extensions: advanced/extensions.md - Custom message handlers: advanced/custom-handlers.md + - Project: + - Deprecation policy: deprecation-policy.md + - SDK tier target: sdk-tier.md - Examples: examples.md - API Reference: https://php.sdk.modelcontextprotocol.io/api/ From d726b4d8aa129039a15cdba1e0c3243b9ccba66d Mon Sep 17 00:00:00 2001 From: Christopher Hertel Date: Sat, 22 Aug 2026 02:09:47 +0200 Subject: [PATCH 4/8] [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. --- CONTRIBUTING.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 4 ++- 2 files changed, 87 insertions(+), 1 deletion(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..d7362a5a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,84 @@ +# Contributing + +Thanks for considering a contribution to the PHP SDK for the Model Context Protocol. This is a +collaboration between [the PHP Foundation](https://thephp.foundation/) and the +[Symfony project](https://symfony.com/), and it follows Symfony's conventions throughout. + +## Ways to contribute + +- **Report a bug** or **propose a feature** by [opening an issue](https://github.com/modelcontextprotocol/php-sdk/issues). + Check existing issues first — many spec-driven changes are already tracked under the relevant + `2026-07-28`-style release label. +- **Send a pull request** for a fix, a new capability, or a docs improvement. +- **Improve the guides** under `docs/` — see [Documentation](#documentation) below for how they're built. +- **Help close a conformance gap** — `make conformance-tests` runs the official MCP conformance + suite against this SDK; a failing scenario there is a concrete, well-scoped contribution. + +## Development setup + +Requires PHP 8.1+. + +```bash +composer install +``` + +## Before opening a pull request + +Run the full CI suite locally: + +```bash +make ci +``` + +This runs, in order: `make cs` (PHP CS Fixer, auto-fixes style), `make phpstan` (static analysis), +and `make tests` (unit + inspector tests). All three must pass. If your change touches +protocol-observable behavior, also run: + +```bash +make conformance-tests # requires Docker +``` + +## Coding standards + +This project follows [Symfony's coding standards](https://symfony.com/doc/current/contributing/code/standards.html) +and [backward compatibility promise](https://symfony.com/doc/current/contributing/code/bc.html). In short: + +- `declare(strict_types=1);` in every file. +- Type hints on every parameter and return value. +- Final classes by default — only leave a class non-final when it's deliberately designed for extension. +- Prefer immutable value objects. +- DocBlocks explain *why*, not *what* — the code and its types should already say what it does. + +See [CLAUDE.md](CLAUDE.md) for a fuller tour of the codebase's architecture and layout. + +## Tests + +New capabilities need unit tests (`tests/Unit/`) covering the core logic, and — for anything +reachable over the wire — inspector tests (`tests/Inspector/`) for end-to-end coverage. If you're +adding a documented pattern, consider adding or updating an example under `examples/`. + +## Documentation + +The guides under `docs/` are built with [Zensical](https://zensical.org/) in `--strict` mode, +which fails the build on a broken internal link: + +```bash +make docs-guides +``` + +Links between guide pages must be relative paths that resolve within `docs/` (e.g. +`protocol-versions.md`, `../CLAUDE.md` will *not* resolve — Zensical only follows the `docs/` tree). +For anything at the repo root (`CLAUDE.md`, `ROADMAP.md`, `CHANGELOG.md`), link to it by its GitHub +URL instead, matching the pattern already used across `docs/`. The class-level API reference is +generated separately by phpDocumentor (`make docs-api`) and isn't hand-written. + +## Licensing + +New contributions are licensed under Apache License, Version 2.0. Existing code predating this +policy remains under the MIT License — see [LICENSE](LICENSE) for the details. By opening a pull +request, you agree your contribution is provided under those terms. + +## Getting help + +If something is unclear or you want early feedback on an approach before writing code, open an +issue or a draft pull request — that's the right place to ask, rather than guessing at scope. diff --git a/README.md b/README.md index 194230a2..04965f85 100644 --- a/README.md +++ b/README.md @@ -126,7 +126,9 @@ Building something on top of the SDK? Open a pull request to add it to this list We are passionate about supporting contributors of all levels of experience and would love to see you get involved in the project. Start by [reporting issues](https://github.com/modelcontextprotocol/php-sdk/issues) or -[sending pull requests](https://github.com/modelcontextprotocol/php-sdk/pulls). +[sending pull requests](https://github.com/modelcontextprotocol/php-sdk/pulls). See +[CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding standards, and what to run before +opening a PR. ## Credits From 3ed2b5e4ed78dfe947823132d4466ac6356360cb Mon Sep 17 00:00:00 2001 From: Christopher Hertel Date: Sat, 22 Aug 2026 02:26:54 +0200 Subject: [PATCH 5/8] [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/deprecation-policy.md | 21 +-------------------- 1 file changed, 1 insertion(+), 20 deletions(-) diff --git a/docs/deprecation-policy.md b/docs/deprecation-policy.md index bd391219..77c81b98 100644 --- a/docs/deprecation-policy.md +++ b/docs/deprecation-policy.md @@ -19,28 +19,9 @@ SDK-internal deprecation) that introduced the deprecation and the earliest remov */ ``` -This is already in place for the first real instance of the policy: SEP-2577 deprecated Roots, Sampling and -Logging in the `2026-07-28` revision (merged in #427). Twenty-seven call sites across `src/Schema/`, -`src/Client/` and `src/Server/` carry the tag today — see `RootsListChangedNotification`, -`SetLogLevelRequest`, `LoggingMessageNotification`, `SamplingCallbackInterface`, and others. Each keeps -working exactly as before; the tag is a migration signal, not a behavior change. The CHANGELOG entry for -that release states the same window and points at the replacement for each: tool arguments or resource URIs -instead of roots, a direct LLM provider integration instead of sampling, `stderr`/OpenTelemetry instead of -`notifications/message`. - ## The SDK's own BC promise -The SDK is pre-1.0 and experimental — the root `README.md` and `CLAUDE.md` say so plainly, and the public +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. - -## Relationship to the protocol lifecycle - -This document covers deprecation as an API-surface concern: what gets tagged, for how long, with what -migration note. It's a different (related) axis from -[protocol era support](protocol-versions.md#what-was-removed) — which protocol revisions the SDK serves at -all, and what a given revision no longer accepts on the wire. A method can be removed from the modern -revision's wire surface while its PHP binding stays present and undeprecated, because a handshake-era client -still needs it; see [Protocol versions](protocol-versions.md)' "What was removed" and "Deprecations" -sections for the current list. From 86adfb2cc677897d8e35042b781cd441f614387f Mon Sep 17 00:00:00 2001 From: Christopher Hertel Date: Sat, 22 Aug 2026 02:27:02 +0200 Subject: [PATCH 6/8] [Docs] Cite the Tier 3 audit and add a versioning policy (SEP-1730) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- CONTRIBUTING.md | 6 +++ docs/sdk-tier.md | 113 +++++++++++++++++++++++++++-------------------- 2 files changed, 70 insertions(+), 49 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d7362a5a..0ac104df 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -72,6 +72,12 @@ For anything at the repo root (`CLAUDE.md`, `ROADMAP.md`, `CHANGELOG.md`), link URL instead, matching the pattern already used across `docs/`. The class-level API reference is generated separately by phpDocumentor (`make docs-api`) and isn't hand-written. +## Versioning + +The SDK follows [Semantic Versioning](https://semver.org/) — see +[SDK tier target](docs/sdk-tier.md#versioning) for what that means pre- and post-1.0, and how it +lines up with Symfony's backward compatibility promise. + ## Licensing New contributions are licensed under Apache License, Version 2.0. Existing code predating this diff --git a/docs/sdk-tier.md b/docs/sdk-tier.md index a7aca28b..7ba3bc85 100644 --- a/docs/sdk-tier.md +++ b/docs/sdk-tier.md @@ -2,60 +2,75 @@ 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 against the Tier 2 bar and what's still missing. +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 now, Tier 1 after the 1.0 release.** - -Tier 1 requires a stable release with clear versioning. The SDK is currently -pre-1.0 and experimental (see -[CLAUDE.md](https://github.com/modelcontextprotocol/php-sdk/blob/main/CLAUDE.md)), -so Tier 1 is structurally out of reach until 1.0 ships regardless of how -complete any other Tier 1 criterion is. Tier 2 has no such blocker and is -achievable now. - -## Gap analysis against Tier 2 - -| Requirement | Status | Evidence | -|---|---|---| -| ≥80% conformance | **Gap — server yes, client no** | Server: 144/145 (99%) on 2026-07-28, 39/40 (98%) on 2025-11-25. Client: 16/80 (20%) on 2026-07-28, 2/44 (5%) on 2025-11-25. The SDK is strong on the server surface and far below the bar on the client surface. This is the single largest gap to Tier 2 — closing it means building out client-side conformance coverage, not just docs/process. | -| New features within 6 months of a spec release | Informal, not tracked | No published SLA. The `2026-07-28`-labeled issue set and this triage effort are the closest thing to a tracked adoption process today; nothing publishes a commitment. | -| Triage within a month | Informal, not tracked | No published triage SLA. Labels exist to support one (see below) but aren't backed by a stated commitment. | -| P0 fix ≤2 weeks | Informal, not tracked | `P0`–`P3` labels exist and are used, but no published response-time commitment. | -| ≥1 stable release | Not yet | SDK is pre-1.0. | -| Basic docs | **Met** | `docs/` covers the builder API, client, transports, elements, events, authorization, extensions, and the stateless lifecycle. | -| Standardized GitHub label set | **Met** | `bug`, `enhancement`, `question`, `needs confirmation`, `needs repro`, `ready for work`, `good first issue`, `help wanted`, `P0`–`P3` are all present and in active use (confirmed via `gh label list`). | -| Published dependency-update policy | **Gap — mechanism exists, not documented** | `make deps-stable` / `make deps-low` (wired into `ci-stable` / `ci-lowest`) already test against both the newest and lowest-compatible dependency sets on every CI run. There's no doc stating this as a policy or naming a support window. | - -## What closes the gap - -Roughly in priority order: - -1. **Client conformance.** This is the real blocker, not a doc gap. The - client suite is failing the large majority of scenarios (20% / 5%). - Investigate what's actually failing before assuming it's missing - features vs. test/harness gaps — either way this needs engineering work, - tracked separately from this doc. -2. **Publish the dependency-update policy.** The mechanism (`deps-stable`, - `deps-low` in CI) already enforces support for both the newest and the - lowest compatible dependency versions on every run. What's missing is a - short published statement saying so, so it counts as "published" rather - than merely "true." That's a stated policy, not new code: - > The SDK's `composer.json` constraints are tested on every CI run - > against both the newest allowed versions (`make deps-stable`) and the - > lowest allowed versions (`make deps-low`), so both ends of the declared - > range are guaranteed to work. Dependency bumps land as regular PRs; - > there's no separate deprecation/removal schedule for dependencies - > beyond what `composer.json`'s version constraints already express. -3. **State the triage/response SLAs**, once the team is actually willing to - commit to the Tier 2 numbers (triage within a month, P0 fix within two - weeks). Labels already exist to support this; only the commitment itself - is missing, and it isn't this document's call to make. +**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.** + +Two process gaps the audit also flagged, now addressed: + +- **Published dependency-update policy** — already enforced in CI + (`make deps-stable` / `make deps-low` test the newest and lowest allowed + dependency sets on every run) and declared in + [`.github/dependabot.yml`](https://github.com/modelcontextprotocol/php-sdk/blob/main/.github/dependabot.yml). +- **Versioning policy** — see below; this section is the fix. + +## 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 a narrower and more mechanical -thing than the feature roadmap. +process/tier-classification gap, which is narrower and more mechanical than +the feature roadmap. From 592d73b9aa21af173dadb2f07c48ea464476a93d Mon Sep 17 00:00:00 2001 From: Christopher Hertel Date: Sat, 22 Aug 2026 02:38:32 +0200 Subject: [PATCH 7/8] [Docs] Link Symfony's BC promise from the deprecation policy Was plain text; sdk-tier.md's Versioning section already links it. --- docs/deprecation-policy.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/deprecation-policy.md b/docs/deprecation-policy.md index 77c81b98..4f512dd8 100644 --- a/docs/deprecation-policy.md +++ b/docs/deprecation-policy.md @@ -23,5 +23,6 @@ SDK-internal deprecation) that introduced the deprecation and the earliest remov 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 +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. From 94600e0654b69f997beaf8a037644d2080096663 Mon Sep 17 00:00:00 2001 From: Christopher Hertel Date: Sat, 22 Aug 2026 02:39:28 +0200 Subject: [PATCH 8/8] [Docs] Drop the "process gaps addressed" aside from sdk-tier.md --- docs/sdk-tier.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/docs/sdk-tier.md b/docs/sdk-tier.md index 7ba3bc85..8fe7e8d3 100644 --- a/docs/sdk-tier.md +++ b/docs/sdk-tier.md @@ -47,14 +47,6 @@ Roughly in priority order, per the audit's own recommendation: `elicitation-sep1034-client-defaults`, both scored at 2025-11-25). 3. **Ship a stable 1.0.0+ release.** -Two process gaps the audit also flagged, now addressed: - -- **Published dependency-update policy** — already enforced in CI - (`make deps-stable` / `make deps-low` test the newest and lowest allowed - dependency sets on every run) and declared in - [`.github/dependabot.yml`](https://github.com/modelcontextprotocol/php-sdk/blob/main/.github/dependabot.yml). -- **Versioning policy** — see below; this section is the fix. - ## Versioning The SDK follows [Semantic Versioning](https://semver.org/):