|
3 | 3 | Thank you for your interest in contributing to the Model Context Protocol Java SDK! |
4 | 4 | This document outlines how to contribute to this project. |
5 | 5 |
|
| 6 | +## Before you start |
| 7 | + |
| 8 | +> [!IMPORTANT] |
| 9 | +> **The most useful contribution is a good issue.** Pull requests from outside |
| 10 | +> the maintainer team are closed automatically unless they link an issue |
| 11 | +> assigned to their author. |
| 12 | +
|
| 13 | +### Why issues rather than pull requests |
| 14 | + |
| 15 | +Coding agents can now turn any open issue into a plausible-looking pull request within |
| 16 | +hours, and generate speculative bug reports from a scan of the code, so we |
| 17 | +receive far more issues and PRs than we can read carefully. Reviewing a PR |
| 18 | +properly still takes as long as it always did. When an issue is well described, |
| 19 | +it is usually quicker for a maintainer to write a fix that fits the codebase |
| 20 | +than to review and reshape someone else's. |
| 21 | + |
| 22 | +What we can't produce ourselves is your context: what you were doing, what you |
| 23 | +expected, a minimal reproduction, and the system where it broke. |
| 24 | +That is what a good issue carries, so that is what we ask for first. |
| 25 | + |
| 26 | +### How pull requests get in |
| 27 | + |
| 28 | +A PR from someone outside the maintainer team stays open when both of these |
| 29 | +hold: |
| 30 | + |
| 31 | +1. Its description links an open issue in this repository with `Fixes #123` |
| 32 | + (or `Closes`, `Resolves`), or with `Updates #123` for a partial fix. |
| 33 | +2. A maintainer has assigned that issue to you, or the issue carries the [`help |
| 34 | + wanted`](https://github.com/modelcontextprotocol/java-sdk/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22help%20wanted%22) |
| 35 | + label, which means we'd welcome a PR for it from anyone. |
| 36 | + |
| 37 | +Otherwise a bot labels the PR `missing-issue-link`, leaves a comment explaining |
| 38 | +this, and closes it. Drafts are treated the same way. If that happens to yours, |
| 39 | +there's no need to open a new one: it reopens automatically as soon as a |
| 40 | +maintainer assigns you the issue, or when you edit the description to link one |
| 41 | +that qualifies. While it's closed, push updates as new commits rather than |
| 42 | +force-pushing, since GitHub can't reopen a PR whose branch has been rewritten. |
| 43 | +This applies to small fixes like typos too; for those, an issue pointing at the |
| 44 | +problem is all we need. |
| 45 | + |
| 46 | +Whether to assign an issue, and to whom, is a maintainer call, and it depends |
| 47 | +on our capacity at the time as much as on the change itself. Comments that only |
| 48 | +ask to be assigned don't factor into it, so please skip those (and don't have |
| 49 | +an agent post them). What does help is engaging with the issue itself: |
| 50 | +confirming the reproduction, asking about the intended behavior, or briefly |
| 51 | +describing the approach you'd take. If you reported the issue and would like to |
| 52 | +fix it yourself, say so in the issue. |
| 53 | + |
| 54 | +Maintainers can override the check by reopening the PR, by removing its |
| 55 | +`missing-issue-link` label, or by adding `bypass-issue-check`. |
| 56 | + |
6 | 57 | ## Prerequisites |
7 | 58 |
|
8 | 59 | The following software is required to work on the codebase: |
@@ -69,25 +120,23 @@ git checkout -b feature/your-feature-name |
69 | 120 |
|
70 | 121 | ## Submitting Changes |
71 | 122 |
|
72 | | -Please don't submit pull requests: |
| 123 | +**Before submitting a PR, please first open an issue and wait until it is assigned to you.** |
73 | 124 |
|
74 | | -- With GitHub accounts managed by autonomous AI bots |
75 | | -- For already assigned issues (as the assignee is or plans to work on it) |
| 125 | +Please don't submit issues or pull requests with GitHub accounts managed by autonomous AI bots. |
76 | 126 |
|
77 | 127 | When submitting changes: |
78 | 128 |
|
79 | | -1. For non-trivial changes, please clarify with the maintainers in an issue whether |
80 | | - you can contribute the change and the desired scope of the change. |
81 | | -2. For trivial changes (for example a couple of lines or documentation changes) there |
82 | | - is no need to open an issue first. |
83 | | -3. Maintainers will triage issues and act on them. There is no such guarantee on pull requests. |
84 | | - PRs opened without being discussed in an issue MAY be ignored, and maintainers reserve the right |
85 | | - to close these PRs without justification. |
86 | | -4. Push your changes to your fork. |
87 | | -5. Submit a pull request to the main repository. |
88 | | -6. Follow the pull request template. |
89 | | -7. Wait for review. |
90 | | -8. For any follow-up work, please add new commits instead of force-pushing. This will |
| 129 | +1. Every PR from outside the maintainer team must link an issue that a maintainer |
| 130 | + has assigned to you, or one labeled `help wanted`, as described in [How pull |
| 131 | + requests get in](#how-pull-requests-get-in). For changes that don't relate to an |
| 132 | + existing issue, file an issue first, clarify the desired scope of the change with |
| 133 | + the maintainers, and wait for it to be assigned before opening a PR. |
| 134 | +2. Maintainers will triage issues and act on them. There is no such guarantee on pull requests. |
| 135 | +3. Push your changes to your fork. |
| 136 | +4. Submit a pull request to the main repository. |
| 137 | +5. Follow the pull request template. |
| 138 | +6. Wait for review. |
| 139 | +7. For any follow-up work, please add new commits instead of force-pushing. This will |
91 | 140 | allow the reviewer to focus on incremental changes instead of having to restart the |
92 | 141 | review process. |
93 | 142 |
|
|
0 commit comments