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
84 lines
3.3 KiB
Markdown
84 lines
3.3 KiB
Markdown
# 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.
|