Providing a pull request review¶
We're always happy to have reviews from contributors, regardless of their experience level.
Why review contributions?¶
Every contribution that is submitted needs to be reviewed, regardless of whether it was submitted by a core team member or a first-time contributor. Everyone has the potential to miss something. The review process is in place to provide an extra safety net.
The purpose of the review process is to ensure all content, including code and documentation, is as bug-free and easy-to-maintain as possible. Anything you can do to further that goal is a welcome contribution. This could ranging from something as simple as correcting a typo, to finding edge cases in the API usage that aren't being caught. You could identify ways the testing regimen could be more robust, or make a suggestion of ways to structure the overall architecture of the changes so that they are easier to maintain or extend.
Can I review?¶
Yes! You can offer a review on any pull request you see open on BeeWare Docs Tools.
As a first-time contributor, you should feel free to review any pull request you find, even if it was submitted by a core team member. If you're a novice, you might be missing some larger project context; but we aim to keep the codebase approachable regardless of your level of experience. If there's something in the code that doesn't make sense, that might indicate there's a need for more documentation (either in the code, or as standalone design documentation).
Contributing a pull request review¶
Providing a pull request review
Everyone is welcome to review any contribution to the BeeWare project. There are some important considerations to be aware of before getting started.
THINK before you review¶
Before engaging in a review, THINK. As reviewers, we should consider whether the response we're about to send is:
- True. Always strive to provide accurate suggestions and information.
- Helpful. We are providing guidance on how to improve the submission; this guidance should clearly identify the source of a problem or an unconsidered use case, and ideally provides a path forward for what would resolve or satisfy the concern.
- Inspiring. It is up to us to inspire the author to want to work through our requested changes.
- Necessary. The expectation is that the author will read everything we post; we must respect their time and effort by only posting when necessary.
- Kind. There are multiple ways to present the same feedback; we need to ensure we are choosing to be kind, supportive, and constructive with our words.
It is entirely possible to THINK, while also providing an effective review. The concepts discussed above to not preclude pointing out any issues you find with a PR. Contributors won't have the opportunity to improve their contribution if they are unaware of areas needing improvement. The important thing is to remain aware of how you are presenting this feedback. Try to depersonalize your review. Instead of, "You made a mistake," you can say, "This code could be improved." Review the code, not the author.
It's important to remember to provide positive feedback in addition to identifying the areas needing improvement. If, for example, the changes are especially helpful, do something particularly clever, or you are introduced to an API that you didn't know about, let the author know! Never underestimate the effect of pointing out something someone has done correctly or well, in the middle of a situation where everything else you've pointed out are issues that need to be resolved.
GitHub review suggestions¶
The GitHub review interface has a mechanism for change suggestions, in which you can provide the exact change you are suggesting as a replacement for the existing content. Keep in mind that, until they are accepted and committed, these suggested changes won't be run through pre-commit and the linting checks. Therefore, this feature should be used for smaller changes, as the larger the suggested change is, the more likely it is to introduce issues.