Watch

Christopher Hertel 1e9520e731

[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

2026-08-24 01:23:52 +02:00

3.3 KiB

Raw Blame History

Contributing

Thanks for considering a contribution to the PHP SDK for the Model Context Protocol. This is a collaboration between the PHP Foundation and the Symfony project, and it follows Symfony's conventions throughout.

Ways to contribute

Report a bug or propose a feature by opening an issue. 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 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+.

composer install

Before opening a pull request

Run the full CI suite locally:

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:

make conformance-tests   # requires Docker

Coding standards

This project follows Symfony's coding standards and backward compatibility promise. In short:

See 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 in --strict mode, which fails the build on a broken internal link:

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 — see SDK tier target 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 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.

3.3 KiB Raw Blame History