[RFC PATCH] MyFirstContribution: mention trimming quoted text in replies

[RFC PATCH] MyFirstContribution: mention trimming quoted text in replies

[Weijie Yuan]

Hi,

Junio has pointed out a few times that over-quoting can make review
discussions harder to follow [1], so I thought it would be helpful to
add a reminder about it in MyFirstContribution. Please feel free to
comment on the patch, as my English is not good.

For your reference:

Git's ReviewingGuidelines [2]:

If a patch is long, you are encouraged to delete parts of it that are
unrelated to your review from the email reply. Make sure to leave enough
context for readers to understand your comments!

The Linux Kernel documentation [3]:

Similarly, please trim all unneeded quotations that aren´t relevant to
your reply. This makes responses easier to find, and saves time and
space.

[1] <xmqqik7tz092.fsf@gitster.g>
[2] https://git-scm.com/docs/ReviewingGuidelines/2.38.0#_performing_your_review
[3] https://docs.kernel.org/process/submitting-patches.html#use-trimmed-interleaved-replies-in-email-discussions

--- >8 ---

ReviewingGuidelines already advises reviewers to trim irrelevant quoted
context when replying. Give the same advice to new contributors in
MyFirstContribution, so our documentation is consistent about mailing
list reply etiquette.

Signed-off-by: Weijie Yuan <wy@wyuan.org>
---
 Documentation/MyFirstContribution.adoc | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc
index 607876f3d8..0e2a9313ce 100644
--- a/Documentation/MyFirstContribution.adoc
+++ b/Documentation/MyFirstContribution.adoc
@@ -1453,6 +1453,11 @@ effect which had not occurred to you. It is always okay to ask for clarification
 if you aren't sure why a change was suggested, or what the reviewer is asking
 you to do.
 
+When replying to review comments, quote only the parts of the message that are
+relevant to your response. It is usually helpful to trim away unrelated context,
+such as large portions of the patch that are not being discussed, while keeping
+enough quoted text for readers to understand what you are responding to.
+
 Make sure your email client has a plaintext email mode and it is turned on; the
 Git list rejects HTML email. Please also follow the mailing list etiquette
 outlined in the
-- 
2.54.0

Re: [RFC PATCH] MyFirstContribution: mention trimming quoted text in replies

[Junio C Hamano]

Weijie Yuan <wy@wyuan.org> writes:

> ReviewingGuidelines already advises reviewers to trim irrelevant quoted
> context when replying. Give the same advice to new contributors in
> MyFirstContribution, so our documentation is consistent about mailing
> list reply etiquette.
>
> Signed-off-by: Weijie Yuan <wy@wyuan.org>

Makes sense.

> diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc
> index 607876f3d8..0e2a9313ce 100644
> --- a/Documentation/MyFirstContribution.adoc
> +++ b/Documentation/MyFirstContribution.adoc
> @@ -1453,6 +1453,11 @@ effect which had not occurred to you. It is always okay to ask for clarification
>  if you aren't sure why a change was suggested, or what the reviewer is asking
>  you to do.
>  
> +When replying to review comments, quote only the parts of the message that are
> +relevant to your response. It is usually helpful to trim away unrelated context,
> +such as large portions of the patch that are not being discussed, while keeping
> +enough quoted text for readers to understand what you are responding to.
> +
>  Make sure your email client has a plaintext email mode and it is turned on; the
>  Git list rejects HTML email. Please also follow the mailing list etiquette
>  outlined in the

The insertion point is well chosen, immediately following the
discussion on how to handle review comments and before the technical
details of email client configuration. The text itself is clear and
gives sound advice.

Will queue and wait for others to weigh in.  Thanks.