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/2] 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/2] 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