Skip to content

Commit 93f69ea

Browse files
committed
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
1 parent 6b5b09a commit 93f69ea

File tree

1 file changed

+29
-7
lines changed

1 file changed

+29
-7
lines changed

CONTRIBUTING.md

Lines changed: 29 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ Thank you for your interest in contributing to the MCP Python SDK! This document
66

77
We welcome contributions! These guidelines exist to save everyone time, yours included. Following them means your work is more likely to be accepted.
88

9-
**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.
9+
**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.
1010

1111
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.
1212

@@ -27,11 +27,17 @@ These always require an issue first:
2727

2828
Bug fixes for clear, reproducible issues are welcome—but still create an issue to track the fix.
2929

30-
### Good Candidates for Contribution
30+
### Finding Issues to Work On
3131

32-
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.
32+
| Label | For | Description |
33+
|-------|-----|-------------|
34+
| [`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 |
35+
| [`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 |
36+
| [`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 |
3337

34-
Issues labeled `needs confirmation` or `needs maintainer action` are **not** good candidates—wait for maintainer input before starting work.
38+
Issues labeled `needs confirmation` or `needs maintainer action` are **not** ready for work—wait for maintainer input first.
39+
40+
Before starting, comment on the issue so we can assign it to you. This prevents duplicate effort.
3541

3642
## Development Setup
3743

@@ -102,13 +108,29 @@ pre-commit run --all-files
102108
- Add type hints to all functions
103109
- Include docstrings for public APIs
104110

105-
## Pull Request Process
111+
## Pull Requests
112+
113+
By the time you open a PR, the "what" and "why" should already be settled in an issue. This keeps reviews focused on implementation.
114+
115+
### Scope
116+
117+
Small PRs get reviewed fast. Large PRs sit in the queue.
118+
119+
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.
120+
121+
### What Gets Rejected
122+
123+
- **No prior discussion**: Features or significant changes without an approved issue
124+
- **Scope creep**: Changes that go beyond what was discussed
125+
- **Misalignment**: Even well-implemented features may be rejected if they don't fit the SDK's direction
126+
- **Overengineering**: Unnecessary complexity for simple problems
127+
128+
### Checklist
106129

107130
1. Update documentation as needed
108131
2. Add tests for new functionality
109132
3. Ensure CI passes
110-
4. Maintainers will review your code
111-
5. Address review feedback
133+
4. Address review feedback
112134

113135
## Code of Conduct
114136

0 commit comments

Comments
 (0)