From 960b838a5f114e252546bdc20171b4a4ca7c1d35 Mon Sep 17 00:00:00 2001 From: Ryan Lahfa Date: Mon, 16 Sep 2024 13:17:33 +0200 Subject: [PATCH] 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: Valentin Gagarin --- CONTRIBUTING.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d13585fc144d..b09cbaba14cd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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.