[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

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:
+
+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.
+
+## 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
+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.

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
 

docs/deprecation-policy.md

@@ -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.

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.

docs/sdk-tier.md

@@ -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.

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/