[PATCH v2 1/2] docs: patches: Add a note about reviews and contacting developers

[Erik Skultety]

On Tue, Jul 26, 2022 at 10:52:50AM +0200, Peter Krempa wrote:
> Add a note outling best practices around review and responding to it.
> 
> Signed-off-by: Peter Krempa <pkrempa at redhat.com>
> ---
>  docs/submitting-patches.rst | 22 ++++++++++++++++++++++
>  1 file changed, 22 insertions(+)
> 
> diff --git a/docs/submitting-patches.rst b/docs/submitting-patches.rst
> index 7bc22323ee..965e381cc1 100644
> --- a/docs/submitting-patches.rst
> +++ b/docs/submitting-patches.rst
> @@ -89,3 +89,25 @@ Moreover, such patch needs to be prefixed correctly with
>  ``--subject-prefix=PATCHv2`` appended to
>  ``git send-email`` (substitute ``v2`` with the
>  correct version if needed though).
> +
> +Reviews

I think 'Review process' sounds better

> +-------
> +
> +Reviewing patches may take a lot of effort and review bandwidth is a limited

I'd reword this a bit:

'Reviewing patches...lot of effort with review bandwidth being limited in
open source projects'

and the reason for this being that if not read carefully until the
end of the sentence, what you'll see is '(a lot of effort AND review bandwidth)'
as a direct connection to the first part of the sentence with the rest of the
sentence then making no sense.
I apologize if I suggested that wording in the previous revision of this patch.

> +resource for open source projects. Here are a few rules to follow to streamline
> +the process:
> +
> + - **don't** contact individual maintainers/developers directly with your
> +   patches; reviewers are subscribed to the mailing list
> + - **do** be patient; reviewers may be busy
> + - **do** respond to reviewer's questions
> + - **don't** ignore a suggestion from a reviewer; if you disagree discuss it on
> +   the list before sending a new version
> + - **do** remind us of your patches on the list if they haven't gotten any
> +   attention for a prolonged period (> week) by replying to your patches with a

s/week/1 week/

> +   "ping"
> + - **do** test your pathches before sending

s/pathches/patches

> +
> +You can also help out by reviewing other patches on the list if you feel
> +comfortable. Don't hesitate to point out apparent problems in idividual patches,
> +you are not obliged to review the whole series.

It would be probably better to invert the last sentence to:

"Don't feel obliged to review whole patch series if you see any major problems
in any of the comprising patches - just point them out and let the author to
respin the series."

Reviewed-by: Erik Skultety <eskultet at redhat.com>