Unverified Commit 960b838a authored by Ryan Lahfa's avatar Ryan Lahfa Committed by GitHub
Browse files

CONTRIBUTING: offer clearer guidelines about blocker vs. non-blocker issues (#264651) 



We sometimes have reviews that are blocked because of miscommunication between author
and reviewer, we make this clear so that reviewers and authors can refer to a block of
"authoritative" text to unblock their own situations.

Co-authored-by: default avatarValentin Gagarin <valentin@gagarin.work>
parent 8c9630d2

CONTRIBUTING.md

+16 −0
Original line number Diff line number Diff line
@@ -315,6 +315,22 @@ When reviewing a pull request, please always be nice and polite. Controversial c 


GitHub provides reactions as a simple and quick way to provide feedback to pull requests or any comments. The thumb-down reaction should be used with care and if possible accompanied with some explanation so the submitter has directions to improve their contribution.



When doing a review:

- Aim to drive the proposal to a timely conclusion.

- Focus on the proposed changes to keep the scope of the discussion narrow.

- Help the contributor prioritise their efforts towards getting their change merged.



If you find anything related that could be improved but is not immediately required for acceptance, consider

- Implementing the changes yourself in a follow-up pull request (and request review from the person who inspired you)

- Tracking your idea in an issue

- Offering the original contributor to review a follow-up pull request

- Making concrete [suggestions](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/incorporating-feedback-in-your-pull-request) in the same pull request.



For example, follow-up changes could involve refactoring code in the affected files.



But please remember not to make such additional considerations a blocker, and communicate that to the contributor, for example by following the [conventional comments](https://conventionalcomments.org/) pattern.

If the related change is essential for the contribution at hand, make clear why you think it is important to address that first.



Pull request reviews should include a list of what has been reviewed in a comment, so other reviewers and mergers can know the state of the review.



All the review template samples provided in this section are generic and meant as examples. Their usage is optional and the reviewer is free to adapt them to their liking.