From 71ffdc7d761e2feb6edc779e54eb21936c002399 Mon Sep 17 00:00:00 2001 From: Max Isbey <224885523+maxisbey@users.noreply.github.com> Date: Tue, 9 Dec 2025 19:10:35 +0000 Subject: [PATCH 1/3] docs: add guidance on discussing features before opening PRs Adds a "Before You Start" section to CONTRIBUTING.md that: - Encourages opening issues before significant PRs - Defines what counts as "significant" changes - Points contributors to well-labeled issues - Warns against working on issues needing maintainer input This gives maintainers clear policy to reference when closing unsolicited large PRs that weren't previously discussed. --- CONTRIBUTING.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c18937f5b3..12fcff5f47 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,6 +2,29 @@ Thank you for your interest in contributing to the MCP Python SDK! This document provides guidelines and instructions for contributing. +## Before You Start + +### Bug Fixes + +Bug fixes are welcome! For straightforward bugs, feel free to open a PR directly. For complex bugs that require significant changes, consider opening an issue first to discuss the approach. + +### New Features and Enhancements + +**Please open an issue before starting work on new features or significant enhancements.** We will often close pull requests for new features that were not previously discussed. This isn't because we don't appreciate the contribution—it's because adding features creates long-term maintenance burden and requires alignment with the SDK's direction. + +What counts as "significant"? + +- New public APIs or decorators +- Architectural changes or refactoring +- Changes that touch multiple modules +- Features that might require spec changes (these need a [SEP](https://github.com/modelcontextprotocol/modelcontextprotocol) first) + +### Good Candidates for Contribution + +Issues labeled [`good first issue`](https://github.com/modelcontextprotocol/python-sdk/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) or [`help wanted`](https://github.com/modelcontextprotocol/python-sdk/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) are great places to start. Issues labeled [`ready for work`](https://github.com/modelcontextprotocol/python-sdk/issues?q=is%3Aopen+is%3Aissue+label%3A%22ready+for+work%22) have been triaged and are ready for implementation. + +Issues labeled `needs confirmation` or `needs maintainer action` are **not** good candidates—please wait for maintainer input before starting work on these. + ## Development Setup 1. Make sure you have Python 3.10+ installed From 6b5b09a69dccb44a2a6e6338dfb3f2611a9ef203 Mon Sep 17 00:00:00 2001 From: Max Isbey <224885523+maxisbey@users.noreply.github.com> Date: Thu, 11 Dec 2025 11:52:13 +0000 Subject: [PATCH 2/3] docs: strengthen contributing guidelines - Require issues for all PRs (except trivial fixes like typos) - Add requirement to wait for maintainer buy-in before starting work - Add "SDK is opinionated" section for maintainer discretion - Restructure with clearer "What Needs Discussion" section - Add welcoming opening to balance strict rules --- CONTRIBUTING.md | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 12fcff5f47..9215bdaf73 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,26 +4,34 @@ Thank you for your interest in contributing to the MCP Python SDK! This document ## Before You Start -### Bug Fixes +We welcome contributions! These guidelines exist to save everyone time, yours included. Following them means your work is more likely to be accepted. -Bug fixes are welcome! For straightforward bugs, feel free to open a PR directly. For complex bugs that require significant changes, consider opening an issue first to discuss the approach. +**All pull requests require a corresponding issue.** Unless your change is trivial (typo, docs tweak, broken link), create an issue first. PRs without a linked issue will be closed. -### New Features and Enhancements +Having an issue doesn't guarantee acceptance. Wait for maintainer feedback or a `ready for work` label before starting. PRs for issues without buy-in may also be closed. -**Please open an issue before starting work on new features or significant enhancements.** We will often close pull requests for new features that were not previously discussed. This isn't because we don't appreciate the contribution—it's because adding features creates long-term maintenance burden and requires alignment with the SDK's direction. +Use issues to validate your idea before investing time in code. PRs are for execution, not exploration. -What counts as "significant"? +### The SDK is Opinionated + +Not every contribution will be accepted, even with a working implementation. We prioritize maintainability and consistency over adding capabilities. This is at maintainers' discretion. + +### What Needs Discussion + +These always require an issue first: - New public APIs or decorators - Architectural changes or refactoring - Changes that touch multiple modules - Features that might require spec changes (these need a [SEP](https://github.com/modelcontextprotocol/modelcontextprotocol) first) +Bug fixes for clear, reproducible issues are welcome—but still create an issue to track the fix. + ### Good Candidates for Contribution -Issues labeled [`good first issue`](https://github.com/modelcontextprotocol/python-sdk/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) or [`help wanted`](https://github.com/modelcontextprotocol/python-sdk/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) are great places to start. Issues labeled [`ready for work`](https://github.com/modelcontextprotocol/python-sdk/issues?q=is%3Aopen+is%3Aissue+label%3A%22ready+for+work%22) have been triaged and are ready for implementation. +Issues labeled [`good first issue`](https://github.com/modelcontextprotocol/python-sdk/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) or [`help wanted`](https://github.com/modelcontextprotocol/python-sdk/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) are great starting points. Issues labeled [`ready for work`](https://github.com/modelcontextprotocol/python-sdk/issues?q=is%3Aopen+is%3Aissue+label%3A%22ready+for+work%22) have been triaged and are ready for implementation. -Issues labeled `needs confirmation` or `needs maintainer action` are **not** good candidates—please wait for maintainer input before starting work on these. +Issues labeled `needs confirmation` or `needs maintainer action` are **not** good candidates—wait for maintainer input before starting work. ## Development Setup From 93f69eac834eb3335d1d34a7d6cb84298d480418 Mon Sep 17 00:00:00 2001 From: Max Isbey <224885523+maxisbey@users.noreply.github.com> Date: Wed, 31 Dec 2025 14:45:21 +0000 Subject: [PATCH 3/3] docs: improve contributing guidelines with clearer structure - Add explanation of why issues are required (maintenance burden) - Replace label paragraph with table showing who each label is for - Add guidance to comment on issues before starting work - Expand PR section with scope guidance and rejection criteria --- CONTRIBUTING.md | 36 +++++++++++++++++++++++++++++------- 1 file changed, 29 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9215bdaf73..b4304ff94d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,7 +6,7 @@ Thank you for your interest in contributing to the MCP Python SDK! This document We welcome contributions! These guidelines exist to save everyone time, yours included. Following them means your work is more likely to be accepted. -**All pull requests require a corresponding issue.** Unless your change is trivial (typo, docs tweak, broken link), create an issue first. PRs without a linked issue will be closed. +**All pull requests require a corresponding issue.** Unless your change is trivial (typo, docs tweak, broken link), create an issue first. Every merged feature becomes ongoing maintenance, so we need to agree something is worth doing before reviewing code. PRs without a linked issue will be closed. Having an issue doesn't guarantee acceptance. Wait for maintainer feedback or a `ready for work` label before starting. PRs for issues without buy-in may also be closed. @@ -27,11 +27,17 @@ These always require an issue first: Bug fixes for clear, reproducible issues are welcome—but still create an issue to track the fix. -### Good Candidates for Contribution +### Finding Issues to Work On -Issues labeled [`good first issue`](https://github.com/modelcontextprotocol/python-sdk/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) or [`help wanted`](https://github.com/modelcontextprotocol/python-sdk/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) are great starting points. Issues labeled [`ready for work`](https://github.com/modelcontextprotocol/python-sdk/issues?q=is%3Aopen+is%3Aissue+label%3A%22ready+for+work%22) have been triaged and are ready for implementation. +| Label | For | Description | +|-------|-----|-------------| +| [`good first issue`](https://github.com/modelcontextprotocol/python-sdk/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) | Newcomers | Can tackle without deep codebase knowledge | +| [`help wanted`](https://github.com/modelcontextprotocol/python-sdk/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) | Experienced contributors | Maintainers probably won't get to this | +| [`ready for work`](https://github.com/modelcontextprotocol/python-sdk/issues?q=is%3Aopen+is%3Aissue+label%3A%22ready+for+work%22) | Maintainers | Triaged and ready for a maintainer to pick up | -Issues labeled `needs confirmation` or `needs maintainer action` are **not** good candidates—wait for maintainer input before starting work. +Issues labeled `needs confirmation` or `needs maintainer action` are **not** ready for work—wait for maintainer input first. + +Before starting, comment on the issue so we can assign it to you. This prevents duplicate effort. ## Development Setup @@ -102,13 +108,29 @@ pre-commit run --all-files - Add type hints to all functions - Include docstrings for public APIs -## Pull Request Process +## Pull Requests + +By the time you open a PR, the "what" and "why" should already be settled in an issue. This keeps reviews focused on implementation. + +### Scope + +Small PRs get reviewed fast. Large PRs sit in the queue. + +A few dozen lines can be reviewed in minutes. Hundreds of lines across many files takes real effort and things slip through. If your change is big, break it into smaller PRs or get alignment from a maintainer first. + +### What Gets Rejected + +- **No prior discussion**: Features or significant changes without an approved issue +- **Scope creep**: Changes that go beyond what was discussed +- **Misalignment**: Even well-implemented features may be rejected if they don't fit the SDK's direction +- **Overengineering**: Unnecessary complexity for simple problems + +### Checklist 1. Update documentation as needed 2. Add tests for new functionality 3. Ensure CI passes -4. Maintainers will review your code -5. Address review feedback +4. Address review feedback ## Code of Conduct