Skip to content

Commit 8d1efe9

Browse files
ntBreMichaReiser
andauthored
Add a new "Opening a PR" section to the contribution guide (#21298)
Summary -- This PR adds a new section to CONTRIBUTING.md describing the expected contents of the PR summary and test plan, using the ecosystem report, and communicating the status of a PR. This seemed like a pretty good place to insert this in the document, at the end of the advice on preparing actual code changes, but I'm certainly open to other suggestions about both the content and placement. Test Plan -- Future PRs :) --------- Co-authored-by: Micha Reiser <micha@reiser.io>
1 parent 04e7cec commit 8d1efe9

File tree

1 file changed

+49
-0
lines changed

1 file changed

+49
-0
lines changed

CONTRIBUTING.md

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -280,6 +280,55 @@ Note that plugin-specific configuration options are defined in their own modules
280280

281281
Finally, regenerate the documentation and generated code with `cargo dev generate-all`.
282282

283+
### Opening a PR
284+
285+
After you finish your changes, the next step is to open a PR. By default, two
286+
sections will be filled into the PR body: the summary and the test plan.
287+
288+
#### The summary
289+
290+
The summary is intended to give us as maintainers information about your PR.
291+
This should typically include a link to the relevant issue(s) you're addressing
292+
in your PR, as well as a summary of the issue and your approach to fixing it. If
293+
you have any questions about your approach or design, or if you considered
294+
alternative approaches, that can also be helpful to include.
295+
296+
AI can be helpful in generating both the code and summary of your PR, but a
297+
successful contribution should still be carefully reviewed by you and the
298+
summary editorialized before submitting a PR. A great summary is thorough but
299+
also succinct and gives us the context we need to review your PR.
300+
301+
You can find examples of excellent issues and PRs by searching for the
302+
[`great writeup`](https://github.com/astral-sh/ruff/issues?q=label%3A%22great%20writeup%22)
303+
label.
304+
305+
#### The test plan
306+
307+
The test plan is likely to be shorter than the summary and can be as simple as
308+
"Added new snapshot tests for `RUF123`," at least for rule bugs. For LSP or some
309+
types of CLI changes, in particular, it can also be helpful to include
310+
screenshots or recordings of your change in action.
311+
312+
#### Ecosystem report
313+
314+
After opening the PR, an ecosystem report will be run as part of CI. This shows
315+
a diff of linter and formatter behavior before and after the changes in your PR.
316+
Going through these changes and reporting your findings in the PR summary or an
317+
additional comment help us to review your PR more efficiently. It's also a great
318+
way to find new test cases to incorporate into your PR if you identify any
319+
issues.
320+
321+
#### PR status
322+
323+
To help us know when your PR is ready for review again, please either move your
324+
PR back to a draft while working on it (marking it ready for review afterwards
325+
will ping the previous reviewers) or explicitly re-request a review. This helps
326+
us to avoid re-reviewing a PR while you're still working on it and also to
327+
prioritize PRs that are definitely ready for review.
328+
329+
You can also thumbs-up or mark as resolved any comments we leave to let us know
330+
you addressed them.
331+
283332
## MkDocs
284333
285334
> [!NOTE]

0 commit comments

Comments
 (0)