Skip to content

Commit b1adfcd

Browse files
felixweinbergerfelixweinberger
authored
Add VERSIONING.md, ROADMAP.md, and DEPENDENCY_POLICY.md (#2084)
1 parent 66aaf93 commit b1adfcd

File tree

6 files changed

+164
-0
lines changed

6 files changed

+164
-0
lines changed

‎.github/dependabot.yml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
version: 2
2+
updates:
3+
- package-ecosystem: "github-actions"
4+
directory: "/"
5+
schedule:
6+
interval: monthly
7+
groups:
8+
github-actions:
9+
patterns:
10+
- "*"

‎.github/workflows/weekly-lockfile-update.yml‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
name: Weekly Lockfile Update
2+
3+
on:
4+
workflow_dispatch:
5+
schedule:
6+
# Every Thursday at 8:00 UTC
7+
- cron: "0 8 * * 4"
8+
9+
permissions:
10+
contents: write
11+
pull-requests: write
12+
13+
jobs:
14+
update-lockfile:
15+
runs-on: ubuntu-latest
16+
steps:
17+
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
18+
19+
- uses: astral-sh/setup-uv@803947b9bd8e9f986429fa0c5a41c367cd732b41 # v7.2.1
20+
with:
21+
version: 0.9.5
22+
23+
- name: Update lockfile
24+
run: |
25+
echo '## Updated Dependencies' > pr_body.md
26+
echo '' >> pr_body.md
27+
echo '```' >> pr_body.md
28+
uv lock --upgrade 2>&1 | tee -a pr_body.md
29+
echo '```' >> pr_body.md
30+
31+
- name: Create pull request
32+
uses: peter-evans/create-pull-request@c0f553fe549906ede9cf27b5156039d195d2ece0 # v7
33+
with:
34+
commit-message: "chore: update uv.lock with latest dependencies"
35+
title: "chore: weekly dependency update"
36+
body-path: pr_body.md
37+
branch: weekly-lockfile-update-v1x
38+
delete-branch: true
39+
add-paths: uv.lock
40+
labels: dependencies

‎CONTRIBUTING.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,28 @@ pre-commit run --all-files
6464

6565
9. Submit a pull request to the same branch you branched from
6666

67+
## Dependency Update Policy
68+
69+
See [DEPENDENCY_POLICY.md](DEPENDENCY_POLICY.md) for the full dependency update policy.
70+
71+
When bumping a dependency version manually, update the constraint in `pyproject.toml` then run `uv lock --resolution lowest-direct` (see [RELEASE.md](RELEASE.md)).
72+
73+
Security-relevant dependency updates (P0) are applied within 7 days of public disclosure and backported to active release branches.
74+
75+
The SDK currently supports Python 3.10 through 3.13. New CPython releases are supported within one minor SDK release of their stable release date.
76+
77+
## Triage Process
78+
79+
New issues are triaged by a maintainer within 2 business days. Triage means adding an appropriate label and determining whether the issue is valid.
80+
81+
Issues are labeled per the [SDK Tiering System](https://modelcontextprotocol.io/community/sdk-tiers):
82+
83+
- **Type** (pick one): `bug`, `enhancement`, `question`
84+
- **Status** (pick one): `needs confirmation`, `needs repro`, `ready for work`, `good first issue`, `help wanted`
85+
- **Priority** (if actionable): `P0`, `P1`, `P2`, `P3`
86+
87+
P0 issues are security vulnerabilities (CVSS ≥ 7.0) or core functionality failures that prevent basic MCP operations (connection establishment, message exchange, or use of core primitives). P0 issues must be resolved within 7 days.
88+
6789
## Code Style
6890

6991
- We use `ruff` for linting and formatting

‎DEPENDENCY_POLICY.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Dependency Policy
2+
3+
As a library consumed by downstream projects, the MCP Python SDK takes a conservative approach to dependency updates. Dependencies are kept stable unless there is a specific reason to update, such as a security vulnerability, a bug fix, or a need for new functionality.
4+
5+
## Update Triggers
6+
7+
Dependencies are updated when:
8+
9+
- A **security vulnerability** is disclosed (via GitHub security alerts or PyPI advisories) in a dependency that directly affects the SDK's functionality or its consumers.
10+
- A bug in a dependency directly affects the SDK.
11+
- A new dependency feature is needed for SDK development.
12+
- A dependency drops support for a Python version the SDK still targets.
13+
14+
Routine version bumps without a clear motivation are avoided to minimize churn for downstream consumers.
15+
16+
## What We Don't Do
17+
18+
The SDK does not run ad-hoc version bumps for PyPI dependencies. Updating a dependency can force downstream consumers to adopt that update transitively, which can be disruptive for projects with strict dependency policies.
19+
20+
Dependencies are only updated when there is a concrete reason, not simply because a newer version is available.
21+
22+
## Automated Tooling
23+
24+
- **Lockfile refresh**: The lockfile is updated automatically every Thursday at 08:00 UTC by the [`weekly-lockfile-update.yml`](.github/workflows/weekly-lockfile-update.yml) workflow, which runs `uv lock --upgrade` and opens a PR. This does not alter the minimum or maximum versions for dependencies of the `mcp` package itself.
25+
- **GitHub security updates** are enabled at the repository level and automatically open pull requests for packages with known vulnerabilities. This is a GitHub repo setting, separate from the `dependabot.yml` configuration.
26+
- **GitHub Actions versions** are kept up to date via Dependabot on a monthly schedule (see `.github/dependabot.yml`).
27+
28+
## Pinning and Ranges
29+
30+
Production dependencies use compatible-release specifiers (`~=`) or lower-bound constraints (`>=`) to allow compatible updates. Exact versions are pinned only when necessary to work around a specific issue. The lockfile (`uv.lock`) records exact resolved versions for reproducible installs.

‎ROADMAP.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Roadmap
2+
3+
## Spec Implementation Tracking
4+
5+
The SDK tracks implementation of MCP spec components via GitHub Projects, with a dedicated project board for each spec revision. For example, see the [2025-11-25 spec revision board](https://github.com/orgs/modelcontextprotocol/projects/26).
6+
7+
## Current Focus Areas
8+
9+
### Next Spec Revision
10+
11+
The next MCP specification revision is being developed in the [protocol repository](https://github.com/modelcontextprotocol/modelcontextprotocol). Key areas expected in the next revision include extensions and stateless transports.
12+
13+
The SDK has historically implemented spec changes promptly as they are finalized, with dedicated project boards tracking component-level progress for each revision.
14+
15+
### v2
16+
17+
A major version of the SDK is in active development, tracked via [GitHub Project](https://github.com/orgs/modelcontextprotocol/projects/31). Target milestones:
18+
19+
- **Alpha**: ~mid-March 2026
20+
- **Beta**: ~May 2026
21+
22+
The v2 release is planned to align with the next spec release, expected around mid-2026.

‎VERSIONING.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Versioning Policy
2+
3+
The MCP Python SDK (`mcp`) follows [Semantic Versioning 2.0.0](https://semver.org/).
4+
5+
## Version Format
6+
7+
`MAJOR.MINOR.PATCH`
8+
9+
- **MAJOR**: Incremented for breaking changes (see below).
10+
- **MINOR**: Incremented for new features that are backward-compatible.
11+
- **PATCH**: Incremented for backward-compatible bug fixes.
12+
13+
## What Constitutes a Breaking Change
14+
15+
The following changes are considered breaking and require a major version bump:
16+
17+
- Removing or renaming a public API export (class, function, type, or constant).
18+
- Changing the signature of a public function or method in a way that breaks existing callers (removing parameters, changing required/optional status, changing types).
19+
- Removing or renaming a public type or dataclass/TypedDict field.
20+
- Changing the behavior of an existing API in a way that breaks documented contracts.
21+
- Dropping support for a Python version that is still receiving security updates.
22+
- Removing support for a transport type.
23+
- Changes to the MCP protocol version that require client/server code changes.
24+
25+
The following are **not** considered breaking:
26+
27+
- Adding new optional parameters to existing functions.
28+
- Adding new exports, types, or classes.
29+
- Adding new optional fields to existing types.
30+
- Bug fixes that correct behavior to match documented intent.
31+
- Internal refactoring that does not affect the public API.
32+
- Adding support for new MCP spec features.
33+
- Changes to dev dependencies or build tooling.
34+
35+
## How Breaking Changes Are Communicated
36+
37+
1. **Changelog**: All breaking changes are documented in the GitHub release notes with migration instructions.
38+
2. **Deprecation**: When feasible, APIs are deprecated for at least one minor release before removal using `warnings.warn()` with `DeprecationWarning`, which surfaces warnings at runtime and through static analysis tooling.
39+
3. **Migration guide**: Major version releases include a migration guide describing what changed and how to update.
40+
4. **PR labels**: Pull requests containing breaking changes are labeled with `breaking change`.

0 commit comments

Comments
 (0)