Add a new "Opening a PR" section to the contribution guide #21298
Conversation
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 :)
| We don't currently have any rules around AI usage or disclosure, but remember | ||
| that this PR summary will be our first impression of your PR. The higher its | ||
| quality and accuracy, the more easily we can start reviewing your PR. However | ||
| you generate the contents of this summary, please ensure that it corresponds to | ||
| the code and doesn't include extraneous or misleading information. |
There was a problem hiding this comment.
Would it be worth adding something around keeping things brief of "succinct" as a way to discourage long or overly-fluffed summaries?
There was a problem hiding this comment.
Yeah, I think that's a good idea. I'll think more about how to work it in.
MichaReiser
left a comment
MichaReiser
left a comment
There was a problem hiding this comment.
Thanks for working on this. This is great. I've a few smaller suggestions around pharsing.
| We don't currently have any rules around AI usage or disclosure, but remember | ||
| that this PR summary will be our first impression of your PR. The higher its | ||
| quality and accuracy, the more easily we can start reviewing your PR. However |
There was a problem hiding this comment.
This sounds a bit intimidating (even when not using AI). I think I'd frame it around AI being useful, but a successful AI generated contribution is reviewed and the summary is editoralized before submitting the PR.
| You should fill in the sections above before opening your PR. After opening the | ||
| PR, an ecosystem report will be run as part of CI. This shows a diff of linter |
There was a problem hiding this comment.
| You should fill in the sections above before opening your PR. After opening the | |
| PR, an ecosystem report will be run as part of CI. This shows a diff of linter | |
| After opening the PR, an ecosystem report will be run as part of CI. This shows a diff of linter |
I'd omit this sentence. It's sort of implied by the previous sections
| differences are reported, you should go through them and make sure they look | ||
| correct. After going through the results of the ecosystem check, you should |
There was a problem hiding this comment.
Rather than making this mandatory, I'd formalize this more around how them review and discussing the ecosystem changes helps us being more effective at reviewing their PR.
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 :)