docs: add guidance on discussing features before opening PRs #1760
+56
−3
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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.
- 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
Outdated
|
|
||
| ### 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 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. |
Contributor
There was a problem hiding this comment.
Personally think this should be a bit more nuanced to differentiate between these. As written now it implies anything labelled any of these 3 is good for anyone to start working on which I think isn't necessarily the case.
E.g. take a look at this: https://github.com/modelcontextprotocol/typescript-sdk/pull/1311/changes
Contributor
Author
There was a problem hiding this comment.
Fair! I've pushed some changes and copied some things from the typescript pr
felixweinberger
previously approved these changes
Dec 19, 2025
- 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
maxisbey
added
documentation
Kludex
approved these changes
Jan 1, 2026
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Adds a "Before You Start" section to CONTRIBUTING.md that sets clear expectations for contributors about when to open an issue before submitting a PR.
Motivation and Context
Currently, we occasionally receive large unsolicited PRs (e.g., major refactoring, new architectural patterns) without prior discussion. This creates awkward situations where we have to close well-intentioned contributions because they don't align with the SDK's direction. Having clear policy in CONTRIBUTING.md gives us something to reference and sets expectations upfront.
This is inspired by how Ruff and other major open source projects handle this.
How Has This Been Tested?
N/A - documentation only change. Verified that the issue filter links work correctly.
Breaking Changes
None.
Types of changes
Checklist
Additional context
The new section covers:
good first issue,help wanted, andready for worklabelsneeds confirmationorneeds maintainer action