GNU bug report logs - #68414
[PATCH] doc: Improve documentation for submitting patches

Message received at 68414 <at> debbugs.gnu.org:

Received: (at 68414) by debbugs.gnu.org; 16 Jan 2024 17:45:48 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Tue Jan 16 12:45:47 2024
Received: from localhost ([127.0.0.1]:49702 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1rPnVT-0006Bt-D2
	for submit <at> debbugs.gnu.org; Tue, 16 Jan 2024 12:45:47 -0500
Received: from mail-wm1-f53.google.com ([209.85.128.53]:59477)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <alehabdo@HIDDEN>) id 1rPnVR-00060B-Jg
 for 68414 <at> debbugs.gnu.org; Tue, 16 Jan 2024 12:45:46 -0500
Received: by mail-wm1-f53.google.com with SMTP id
 5b1f17b1804b1-40e86c86a6fso4289955e9.2
 for <68414 <at> debbugs.gnu.org>; Tue, 16 Jan 2024 09:45:44 -0800 (PST)
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
 d=1e100.net; s=20230601; t=1705427139; x=1706031939;
 h=content-transfer-encoding:in-reply-to:subject:from:references:cc:to
 :content-language:user-agent:mime-version:date:message-id
 :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to;
 bh=3OSm2X+449oVrWWRkm4B9uTPef9i2xUtaK1+GEBfyX4=;
 b=ANAmOwGOUjNzbrZ+N0FboxOkGyupAqyI+SVLlDPIr7MzqP2OYazmSzatX7kWkiGtZo
 1ilxWfLAyiCTYpvwNldf29tWjvuCZMFJ2Pm+M5uefqJFftPWbSd/CLkM1Wz74MQ7WGhv
 G056lFN++74yf8sI5NHHjnNA3IJYhaTD920uhuNePde+zY126c1qyXIqYPzsQcR27iuy
 i2/cmgeQebN1diZ/c0AXYR3hc9jv+F5yEXso1NkFuroB1o3XGIg8s+VI0YJrGPxKZofw
 nzeIBve4TxFW5NMTNA6+SNBBaj6SFAvKTdnMy0zzQWoxmAjeQ0a27dZ1dzng7+QYx+pK
 GAAA==
X-Gm-Message-State: AOJu0YyZ4hPU99WCOuoQOtE/X5v6GjpTK2xol6zIDomFkia+gpZOfnhV
 THOpMoQfq5mvpCV1jOgp930=
X-Google-Smtp-Source: AGHT+IEglsyJ527LQH6aFIiM94Id5WOYwQW6toq44xaj2HEfkK2qOoy1ZqG+N0/0H46iPKlt/oFJRQ==
X-Received: by 2002:a05:600c:2046:b0:40d:477c:197 with SMTP id
 p6-20020a05600c204600b0040d477c0197mr1931523wmg.130.1705427138804; 
 Tue, 16 Jan 2024 09:45:38 -0800 (PST)
Received: from [10.1.59.6] (smtpboys.u-pem.fr. [193.50.159.3])
 by smtp.gmail.com with ESMTPSA id
 fm23-20020a05600c0c1700b0040e612aa673sm19887792wmb.17.2024.01.16.09.45.37
 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128);
 Tue, 16 Jan 2024 09:45:38 -0800 (PST)
Message-ID: <4235b5a5-1f6d-dd10-b753-515bc6254377@HIDDEN>
Date: Tue, 16 Jan 2024 18:45:37 +0100
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101
 Thunderbird/102.15.0
Content-Language: en-US
To: =?UTF-8?Q?Cl=c3=a9ment_Lassieur?= <clement@HIDDEN>
References: <90c8dbae96a3554647770b367945329b15526719.1705122523.git.abdo@HIDDEN>
 <874jfhiibz.fsf@HIDDEN>
 <984db445-6323-ec95-ec2c-da4a3915e814@HIDDEN>
 <87il3usbxb.fsf@HIDDEN>
From: Alexandre Hannud Abdo <abdo@HIDDEN>
Subject: Re: [bug#68414] [PATCH] doc: Improve documentation for submitting
 patches
In-Reply-To: <87il3usbxb.fsf@HIDDEN>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 8bit
X-Spam-Score: -2.6 (--)
X-Debbugs-Envelope-To: 68414
Cc: 68414 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -3.6 (---)

Ni! Hi Clément,

I understand. The current version doesn't even make a distinction between inline patches and attached patches, so "you may …, but …" was just the weakest compatible form I found that didn't fundamentally change the message.

But since you're telling me it's fine to suppress it, that's all good and gone. I do have a thought about mentioning things that people could do out of convenience or habit, but won't work. But I'm fine with not talking about it.

One last question, following this reasoning, should I also remove the note about not using "git diff"? It's a similar situation, where just saying "send patches produced by format-patch" should suffice (and I would change "surest way" to "recommended way" or even better "make sure to send", which leaves no ground for doubt about either thing, without being too "rule-y").

Thank you,

ale

.~´

Le 15/01/2024 à 19:12, Clément Lassieur a écrit :
> Hello Alexandre,
>
> On Mon, Jan 15 2024, Alexandre Hannud Abdo wrote:
>
>> Ni! Thank you, we're actually in good agreement.
>>
>> The possibility of sending inline patches is already there in the current documentation. The excerpt you cite is mostly collage of existing text that was spread in different sections.
>>
>> I sought to articulate the possibilities and their preferred order more
>> clearly so people can better weight the consequences. And I actually tried to
>> word it in a way that would discourage inline patches more strongly than the
>> current text. I have sent inline patches in the past, after reading the
>> current text, and I'm sure I would not have sent them with the text I propose.
> The new version goes like: "You may also...".  But the truth is: "you
> must not." (because inline patches just don't work without git
> send-email).  It's a bit harsh, so I believe the best is to avoid
> talking about things that we don't want.
>
>> The only thing is that I did not feel authorized to exclude a possibility when
>> rewriting the doc. But if you tell me I can, I'll happily change the wording
>> to strictly discourage sending inline patches with an email client.
> Rather than discourage, I think it's fine to not talk about it.  We
> don't need to add rules for each use case.
>
> Thanks,
> Clément

-- 
If wars can be started by lies, peace can be started by truth.
https://www.democracynow.org/live/watch_live_the_belmarsh_tribunal_on

Message received at 68414 <at> debbugs.gnu.org:

Received: (at 68414) by debbugs.gnu.org; 15 Jan 2024 18:13:01 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Mon Jan 15 13:13:01 2024
Received: from localhost ([127.0.0.1]:46811 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1rPRSH-00082G-98
	for submit <at> debbugs.gnu.org; Mon, 15 Jan 2024 13:13:01 -0500
Received: from out1-smtp.messagingengine.com ([66.111.4.25]:57247)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <clement@HIDDEN>) id 1rPRSF-000824-QO
 for 68414 <at> debbugs.gnu.org; Mon, 15 Jan 2024 13:13:00 -0500
Received: from compute6.internal (compute6.nyi.internal [10.202.2.47])
 by mailout.nyi.internal (Postfix) with ESMTP id B8E345C00E7;
 Mon, 15 Jan 2024 13:12:54 -0500 (EST)
Received: from mailfrontend2 ([10.202.2.163])
 by compute6.internal (MEProxy); Mon, 15 Jan 2024 13:12:54 -0500
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lassieur.org; h=
 cc:cc:content-transfer-encoding:content-type:content-type:date
 :date:from:from:in-reply-to:in-reply-to:message-id:mime-version
 :references:reply-to:subject:subject:to:to; s=fm2; t=1705342374;
 x=1705428774; bh=2igAL6Fk0R1ISrB9xjHeoyXtBPDinI8w/Ru+wspGUuk=; b=
 GX9hdDWE+hqsM1zfvzWz+1xEIQzFwbOTDTYNmr7Wup84hFwsXdi+2vpFkMGDLSTL
 qKvakf1+DAfeALgCm1hh5yR8nZmfFb2PS9pLMmxHv7i3Gf+16HJ/YX2tmUoiNDBc
 iRKqv/GipVxDSTEGeeD0429AOd/m2K1CyPj0S/yax/VJY7uGBTePbRgLDkUyt4L5
 mfYBhLn6FXwabGGmBwW7knd+BLmV83wuQEhqglq5MgypVekasipkNs9mQtSINpyi
 QUyqa7Zvr4h6oUCtQ3PK6nZy8d4cfcN3y9VTIGtYT4yM+elmtfCeSraRNl8snsm0
 C5/MSRKMRU8g9RY+7H21Bw==
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=
 messagingengine.com; h=cc:cc:content-transfer-encoding
 :content-type:content-type:date:date:feedback-id:feedback-id
 :from:from:in-reply-to:in-reply-to:message-id:mime-version
 :references:reply-to:subject:subject:to:to:x-me-proxy:x-me-proxy
 :x-me-sender:x-me-sender:x-sasl-enc; s=fm3; t=1705342374; x=
 1705428774; bh=2igAL6Fk0R1ISrB9xjHeoyXtBPDinI8w/Ru+wspGUuk=; b=Q
 z18uExLNrI9I6nfHqgJZc5DK+AN4umBDYD1nh/6HTGlj17ztQAEIQ2zeRdXz7L8E
 xD3AEBeKIqg5wEJQDIcbS4TcImXJjcs4EpvTSbghN4YolDa9f7nSgGsVHrYXfXyO
 b5O/RIieNUGw18Khk0MSfNtdZtbrZOiQJn2kk/bilIwUA1fVveIWjKMr93GT5iGC
 1FRSp21VTjTC7jonig0wSDlXjc31r39P7DRhSHSG6y07w1qLqR7iNLQXq74a01Sy
 /iXo4FKIFiOmwyXkzkbUQu/JbBAk/4ZnqzayR4/Vo9Bhn6Z313rTF7bWsJm3+BFP
 8U36dieKef1+/ZUbXwqNA==
X-ME-Sender: <xms:pnWlZVrUGNn-Nnp3spxEyIkB_7-jsA5KWXsptixff92HHkA-XvrRpw>
 <xme:pnWlZXpiSdUYY2Bsns1Zl0maw7dcrJpC8fAeBXBbsbhB7t7cQzUzDCtPO684sShLW
 l9i1Yf4LVOSzxMvR5o>
X-ME-Received: <xmr:pnWlZSPikEoXvLeOfUgEmdhzdAOugau96OCxNUs6eBvzbYXaYdgTkQ>
X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgedvkedrvdejuddguddutdcutefuodetggdotefrod
 ftvfcurfhrohhfihhlvgemucfhrghsthforghilhdpqfgfvfdpuffrtefokffrpgfnqfgh
 necuuegrihhlohhuthemuceftddtnecusecvtfgvtghiphhivghnthhsucdlqddutddtmd
 enucfjughrpefhvfevufgjfhffkfgfgggtgfesthhqredttderjeenucfhrhhomhepvehl
 rohmvghnthcunfgrshhsihgvuhhruceotghlvghmvghntheslhgrshhsihgvuhhrrdhorh
 hgqeenucggtffrrghtthgvrhhnpeegkeehfefftdefffeuveekgfffhfdtudfgudegueeg
 vefgudetffdugfefhfejudenucevlhhushhtvghrufhiiigvpedtnecurfgrrhgrmhepmh
 grihhlfhhrohhmpegtlhgvmhgvnhhtsehlrghsshhivghurhdrohhrgh
X-ME-Proxy: <xmx:pnWlZQ4nAwKNwbKnsy0hfZgXQDgyaOxW1-vsqXyEN9ONnhvhF4Nexg>
 <xmx:pnWlZU75mRGNIhy1Sa0Q7OL15jsqOGfo04dfj77QbXEpE4v9dup1OA>
 <xmx:pnWlZYjWWc1NsrJZZb4lJS0dXI2-sGjwoW8MHFLSQ7QEKZce8Q3h4g>
 <xmx:pnWlZZgAfS0aFqO913ipnYIw-UZjTppTVIvScsuAKkBO6mHwdAeXrQ>
Feedback-ID: i4c21472a:Fastmail
Received: by mail.messagingengine.com (Postfix) with ESMTPA; Mon,
 15 Jan 2024 13:12:53 -0500 (EST)
From: =?utf-8?Q?Cl=C3=A9ment_Lassieur?= <clement@HIDDEN>
To: Alexandre Hannud Abdo <abdo@HIDDEN>
Subject: Re: [bug#68414] [PATCH] doc: Improve documentation for submitting
 patches
In-Reply-To: <984db445-6323-ec95-ec2c-da4a3915e814@HIDDEN> (Alexandre
 Hannud Abdo's message of "Mon, 15 Jan 2024 15:27:23 +0100")
References: <90c8dbae96a3554647770b367945329b15526719.1705122523.git.abdo@HIDDEN>
 <874jfhiibz.fsf@HIDDEN>
 <984db445-6323-ec95-ec2c-da4a3915e814@HIDDEN>
Date: Mon, 15 Jan 2024 19:12:48 +0100
Message-ID: <87il3usbxb.fsf@HIDDEN>
User-Agent: Gnus/5.13 (Gnus v5.13)
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable
X-Spam-Score: -0.7 (/)
X-Debbugs-Envelope-To: 68414
Cc: 68414 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -1.7 (-)

Hello Alexandre,

On Mon, Jan 15 2024, Alexandre Hannud Abdo wrote:

> Ni! Thank you, we're actually in good agreement.
>
> The possibility of sending inline patches is already there in the current=
 documentation. The excerpt you cite is mostly collage of existing text tha=
t was spread in different sections.
>
> I sought to articulate the possibilities and their preferred order more
> clearly so people can better weight the consequences. And I actually trie=
d to
> word it in a way that would discourage inline patches more strongly than =
the
> current text. I have sent inline patches in the past, after reading the
> current text, and I'm sure I would not have sent them with the text I pro=
pose.

The new version goes like: "You may also...".  But the truth is: "you
must not." (because inline patches just don't work without git
send-email).  It's a bit harsh, so I believe the best is to avoid
talking about things that we don't want.

> The only thing is that I did not feel authorized to exclude a possibility=
 when
> rewriting the doc. But if you tell me I can, I'll happily change the word=
ing
> to strictly discourage sending inline patches with an email client.

Rather than discourage, I think it's fine to not talk about it.  We
don't need to add rules for each use case.

Thanks,
Cl=C3=A9ment

Message received at 68414 <at> debbugs.gnu.org:

Received: (at 68414) by debbugs.gnu.org; 15 Jan 2024 14:27:34 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Mon Jan 15 09:27:34 2024
Received: from localhost ([127.0.0.1]:45030 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1rPNw5-0003wR-Fs
	for submit <at> debbugs.gnu.org; Mon, 15 Jan 2024 09:27:33 -0500
Received: from mail-wr1-f50.google.com ([209.85.221.50]:43172)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <alehabdo@HIDDEN>) id 1rPNw3-0003wE-EN
 for 68414 <at> debbugs.gnu.org; Mon, 15 Jan 2024 09:27:32 -0500
Received: by mail-wr1-f50.google.com with SMTP id
 ffacd0b85a97d-33761e291c1so5001126f8f.0
 for <68414 <at> debbugs.gnu.org>; Mon, 15 Jan 2024 06:27:31 -0800 (PST)
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
 d=1e100.net; s=20230601; t=1705328846; x=1705933646;
 h=content-transfer-encoding:in-reply-to:subject:from:content-language
 :references:cc:to:user-agent:mime-version:date:message-id
 :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to;
 bh=p2nXzZibhSaT0MEzOIjwoQPvh2+aj1k73Kdddx24MUQ=;
 b=Y1kpVeCGPCGZhXY1lTyk+caeOPZ+n2JB2PB6v6AbPs3fxG2nh+J5mDTsiBXsA2QT0s
 wunA/evJZZ7u32LS8gCX1ZafMT43+P32S1qs/jZqxN9v9WEXoUzhnaMgfjkHNzhDPqin
 2AqMNNqXzo1rqEkQ8fTUORC7xmedz+M20MjdwbUydMspfzoWIyN6ri1mnbA9lj1xfNx+
 gfTPTEWuEF/FBjSQSEio4rrSKbSzcVSMBDce9vt7o8/mVAWDhp1QfoVToLNUMzOPDyEk
 ap1aAzLa/NssA2FIa/i8bcE57tt+9z4TsbqtWddBz/GShZami6q24CgvelSS4lhkQswY
 z7rw==
X-Gm-Message-State: AOJu0YzyKPhgG47mKofSSUSn3Unpjr3BvQZJkbNuS1tRs222FY17iHi9
 D62FSDHPyxEon75fsW2mBYF/ph8lOE0QKg==
X-Google-Smtp-Source: AGHT+IHB4H3mCXqRfSR5PEeUlIQHH/UqqnecsAsp50c45dOZcw8T4fQsJ3F3p97cpQ8It5amc+QMew==
X-Received: by 2002:adf:a30d:0:b0:336:7add:b82b with SMTP id
 c13-20020adfa30d000000b003367addb82bmr3743780wrb.16.1705328845151; 
 Mon, 15 Jan 2024 06:27:25 -0800 (PST)
Received: from [192.168.43.34] ([37.166.39.1])
 by smtp.gmail.com with ESMTPSA id
 o18-20020a5d4752000000b00336ee9edbb3sm12042855wrs.94.2024.01.15.06.27.24
 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128);
 Mon, 15 Jan 2024 06:27:24 -0800 (PST)
Message-ID: <984db445-6323-ec95-ec2c-da4a3915e814@HIDDEN>
Date: Mon, 15 Jan 2024 15:27:23 +0100
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101
 Thunderbird/102.15.0
To: 68414 <at> debbugs.gnu.org
References: <90c8dbae96a3554647770b367945329b15526719.1705122523.git.abdo@HIDDEN>
 <874jfhiibz.fsf@HIDDEN>
Content-Language: en-US
From: Alexandre Hannud Abdo <abdo@HIDDEN>
Subject: Re: [bug#68414] [PATCH] doc: Improve documentation for submitting
 patches
In-Reply-To: <874jfhiibz.fsf@HIDDEN>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 8bit
X-Spam-Score: -2.6 (--)
X-Debbugs-Envelope-To: 68414
Cc: =?UTF-8?Q?Cl=c3=a9ment_Lassieur?= <clement@HIDDEN>
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -3.6 (---)

Ni! Thank you, we're actually in good agreement.

The possibility of sending inline patches is already there in the current documentation. The excerpt you cite is mostly collage of existing text that was spread in different sections.

I sought to articulate the possibilities and their preferred order more clearly so people can better weight the consequences. And I actually tried to word it in a way that would discourage inline patches more strongly than the current text. I have sent inline patches in the past, after reading the current text, and I'm sure I would not have sent them with the text I propose.

The only thing is that I did not feel authorized to exclude a possibility when rewriting the doc. But if you tell me I can, I'll happily change the wording to strictly discourage sending inline patches with an email client.

Best,

ale

.~´

Le 13/01/2024 à 12:27, Clément Lassieur a écrit :
> On Sat, Jan 13 2024, Ale Abdo wrote:
>
>> ...     You may also send patches inline, as each patch file
>> +generated by @command{git format-patch} is a single valid email message, but
>> +you'd be advised to pay attention if your email client changes anything like
>> +line breaks or indentation, which could potentially break the patches.
> Hi, I haven't read all your patch, but this is wrong, I'm sorry.
> Sending patches inline without using git send-email mostly doesn't work
> for technical issues and is a waste of time for reviewers who try to
> figure out why the patch doesn't apply.  We should not encourage this.
>
> Thanks,
> Clément

-- 
If wars can be started by lies, peace can be started by truth.
https://www.democracynow.org/live/watch_live_the_belmarsh_tribunal_on

Message received at 68414 <at> debbugs.gnu.org:

Received: (at 68414) by debbugs.gnu.org; 13 Jan 2024 11:27:57 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Sat Jan 13 06:27:57 2024
Received: from localhost ([127.0.0.1]:38611 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1rOcBB-0004rh-IV
	for submit <at> debbugs.gnu.org; Sat, 13 Jan 2024 06:27:57 -0500
Received: from wout5-smtp.messagingengine.com ([64.147.123.21]:40047)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <clement@HIDDEN>) id 1rOcB8-0004rT-T8
 for 68414 <at> debbugs.gnu.org; Sat, 13 Jan 2024 06:27:55 -0500
Received: from compute5.internal (compute5.nyi.internal [10.202.2.45])
 by mailout.west.internal (Postfix) with ESMTP id 3A0B33200BA4;
 Sat, 13 Jan 2024 06:27:50 -0500 (EST)
Received: from mailfrontend1 ([10.202.2.162])
 by compute5.internal (MEProxy); Sat, 13 Jan 2024 06:27:50 -0500
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lassieur.org; h=
 cc:cc:content-transfer-encoding:content-type:content-type:date
 :date:from:from:in-reply-to:in-reply-to:message-id:mime-version
 :references:reply-to:subject:subject:to:to; s=fm1; t=1705145269;
 x=1705231669; bh=sYC/JNNnEO7A58TR8izfQBqN+SiL/Supqfs6xHv1l1g=; b=
 F7nqEaEWaE9CpNdtfa+i6mLaxGoTkn8KmaIli65zDsyRh5VQJ+o6uyxq6gL/e8Qo
 n7YOJdcxHVEYMlAupzRb7Z7KqehSH2tM6964u7myHpcDGiXltH3lbg3EZF9/3xyZ
 uqDriSZX16i8/wp6vQDye71FJ39TrEbhd2C38ibu+LVnDFPbZyqqM22dE3/rjb7r
 hVJBut3aAa6kRWTMayjbGNUhhRWuIikwH92Ymwe+VvVWMh4LGpRwpFrDQT5y/iPw
 08EehV2Y5Z5bqm9SBxRNd51HN/Ui2R/kEsV42C93OP4DYcLNtR5WCu2HoE50Y2dV
 T1TtB1qC8Smz2jWEzYwF0g==
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=
 messagingengine.com; h=cc:cc:content-transfer-encoding
 :content-type:content-type:date:date:feedback-id:feedback-id
 :from:from:in-reply-to:in-reply-to:message-id:mime-version
 :references:reply-to:subject:subject:to:to:x-me-proxy:x-me-proxy
 :x-me-sender:x-me-sender:x-sasl-enc; s=fm2; t=1705145269; x=
 1705231669; bh=sYC/JNNnEO7A58TR8izfQBqN+SiL/Supqfs6xHv1l1g=; b=Z
 0rfj7Eyj5FI7WofgvxqsHuvqtECFiRV5oTEAV0yeNmKiOZxvxTdycNxDVG0+bM73
 Py6ErGFqeAxiC1YJj2T+2EsgZZGH4HnoUMiRZqlShcUJ+1ecwHfVdnyf25/QCyb/
 /ZHLD6ykJcr4GuKsNEZ+hMA8AuviuyEN9LaycdgYwK987YuD7WlPFyscN5OJ8b+O
 ATFpaYnygRwoE/pgoCmWvZFEIvrzrt16IzBiePmP3h/V3wEehBU1s4lMUNiPym4q
 GxyFZXgfnO3PSiAAOuWLnmJfIDdFw6/L6LBfhMeyosV3Ox1BHDYCTivObjw2In1M
 QdSBAh3617vfzEWnWHh3w==
X-ME-Sender: <xms:tXOiZSYDoT4Y3k0iMjEd3gAbkwgO6YYQmfKuw2AZ35CAy7-F9eu9Gg>
 <xme:tXOiZVaXYHbPgUCk0ki6w7sI_zwh730zmj8NDkqqVPq2zaAkcJbsGbYAHS1cm0-Fw
 hZS-0hGlgVAeQ-uZ_8>
X-ME-Received: <xmr:tXOiZc8LwD0Pq4_qnpR07szDtj-qvhJlb2GXAd19m6oYIDkPgmW8IA>
X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgedvkedrvdeijedgvdelucetufdoteggodetrfdotf
 fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen
 uceurghilhhouhhtmecufedttdenucesvcftvggtihhpihgvnhhtshculddquddttddmne
 cujfgurhephffvvefujghffffkfgggtgfgsehtqhertddtreejnecuhfhrohhmpeevlhor
 mhgvnhhtucfnrghsshhivghurhcuoegtlhgvmhgvnhhtsehlrghsshhivghurhdrohhrgh
 eqnecuggftrfgrthhtvghrnhepgeekheefffdtfeffueevkefgfffhtddugfdugeeugeev
 gfduteffudfgfefhjedunecuvehluhhsthgvrhfuihiivgeptdenucfrrghrrghmpehmrg
 hilhhfrhhomheptghlvghmvghntheslhgrshhsihgvuhhrrdhorhhg
X-ME-Proxy: <xmx:tXOiZUptGH-cnc5wYLv-nTrQ93l7Gr176ElfA4jYMY4SVv_WVR-gfQ>
 <xmx:tXOiZdrIEjiOFQSQChFeFztIXtSb6fksGEnhZ-q01zhCU-I3Qa3Vag>
 <xmx:tXOiZST9UXZ4XF9qa6uWVM2O0X1Vs_jDRY79q1VqHw-0819gJprYbQ>
 <xmx:tXOiZcQzT6tltKKROSdSgX77a2ZUc5CjJr6YN5ZM-lJlWYsMcD7SBQ>
Feedback-ID: i4c21472a:Fastmail
Received: by mail.messagingengine.com (Postfix) with ESMTPA; Sat,
 13 Jan 2024 06:27:48 -0500 (EST)
From: =?utf-8?Q?Cl=C3=A9ment_Lassieur?= <clement@HIDDEN>
To: Ale Abdo <abdo@HIDDEN>
Subject: Re: [bug#68414] [PATCH] doc: Improve documentation for submitting
 patches
In-Reply-To: <90c8dbae96a3554647770b367945329b15526719.1705122523.git.abdo@HIDDEN>
 (Ale Abdo's message of "Sat, 13 Jan 2024 06:08:43 +0100")
References: <90c8dbae96a3554647770b367945329b15526719.1705122523.git.abdo@HIDDEN>
Date: Sat, 13 Jan 2024 12:27:44 +0100
Message-ID: <874jfhiibz.fsf@HIDDEN>
User-Agent: Gnus/5.13 (Gnus v5.13)
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable
X-Spam-Score: -0.7 (/)
X-Debbugs-Envelope-To: 68414
Cc: 68414 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -1.7 (-)

On Sat, Jan 13 2024, Ale Abdo wrote:

>...     You may also send patches inline, as each patch file
> +generated by @command{git format-patch} is a single valid email message,=
 but
> +you'd be advised to pay attention if your email client changes anything =
like
> +line breaks or indentation, which could potentially break the patches.

Hi, I haven't read all your patch, but this is wrong, I'm sorry.
Sending patches inline without using git send-email mostly doesn't work
for technical issues and is a waste of time for reviewers who try to
figure out why the patch doesn't apply.  We should not encourage this.

Thanks,
Cl=C3=A9ment

Message received at submit <at> debbugs.gnu.org:

Received: (at submit) by debbugs.gnu.org; 13 Jan 2024 05:09:29 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Sat Jan 13 00:09:29 2024
Received: from localhost ([127.0.0.1]:38140 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1rOWGr-0003OY-Ec
	for submit <at> debbugs.gnu.org; Sat, 13 Jan 2024 00:09:29 -0500
Received: from lists.gnu.org ([2001:470:142::17]:42540)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <abdo@HIDDEN>) id 1rOWGm-0003OI-Dg
 for submit <at> debbugs.gnu.org; Sat, 13 Jan 2024 00:09:24 -0500
Received: from eggs.gnu.org ([2001:470:142:3::10])
 by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.90_1) (envelope-from <abdo@HIDDEN>)
 id 1rOWGh-0006nM-Gq
 for guix-patches@HIDDEN; Sat, 13 Jan 2024 00:09:16 -0500
Received: from msg-1.mailo.com ([213.182.54.11] helo=mailo.com)
 by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.90_1) (envelope-from <abdo@HIDDEN>)
 id 1rOWGb-0006yW-5t
 for guix-patches@HIDDEN; Sat, 13 Jan 2024 00:09:14 -0500
Received: by b221-5.in.mailobj.net [192.168.90.25] with ESMTP
 via ip-20.mailobj.net [213.182.54.20]
 Sat, 13 Jan 2024 06:09:06 +0100 (CET)
X-EA-Auth: yvs5IOQ0sh00fXNB49LJ5b6/jNoj+bIU7CNfyTO/WHXpCzKz55fO3a/O1vtspqzGk3tWrDiMoZxYg+4EQFa1FS3JEmObadM5
From: Ale Abdo <abdo@HIDDEN>
To: guix-patches@HIDDEN
Subject: [PATCH] doc: Improve documentation for submitting patches
Date: Sat, 13 Jan 2024 06:08:43 +0100
Message-ID: <90c8dbae96a3554647770b367945329b15526719.1705122523.git.abdo@HIDDEN>
X-Mailer: git-send-email 2.41.0
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Received-SPF: pass client-ip=213.182.54.11; envelope-from=abdo@HIDDEN;
 helo=mailo.com
X-Spam_score_int: -18
X-Spam_score: -1.9
X-Spam_bar: -
X-Spam_report: (-1.9 / 5.0 requ) BAYES_00=-1.9, RCVD_IN_MSPIKE_H5=0.001,
 RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001,
 T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no
X-Spam_action: no action
X-Spam-Score: -0.0 (/)
X-Debbugs-Envelope-To: submit
Cc: Ale Abdo <abdo@HIDDEN>
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -1.0 (-)

Change-Id: Ice47f1f4a54bf930bdff94b6a1e47ce84e8fabc7
---
 doc/contributing.texi | 278 ++++++++++++++++++++++++------------------
 doc/guix.texi         |   4 +-
 2 files changed, 160 insertions(+), 122 deletions(-)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 5707ff5cde..685d936a16 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -1376,23 +1376,25 @@ Formatting Code
 
 @node Submitting Patches
 @section Submitting Patches
+@cindex patch submission
 
-Development is done using the Git distributed version control system.
-Thus, access to the repository is not strictly necessary.  We welcome
-contributions in the form of patches as produced by @code{git
-format-patch} sent to the @email{guix-patches@@gnu.org} mailing list
+Guix is developed using the Git distributed version control system.  Special
+access to the official repository is not necessary in order to contribute.  We
+welcome contributions in the form of patches, as produced by @code{git
+format-patch}, sent to the @email{guix-patches@@gnu.org} mailing list
 (@pxref{Submitting patches to a project,,, git, Git User Manual}).
-Contributors are encouraged to take a moment to set some Git repository
-options (@pxref{Configuring Git}) first, which can improve the
-readability of patches.  Seasoned Guix developers may also want to look
-at the section on commit access (@pxref{Commit Access}).
-
-This mailing list is backed by a Debbugs instance, which allows us to
-keep track of submissions (@pxref{Tracking Bugs and Changes}).
-Each message sent to that mailing list gets a new tracking number
-assigned; people can then follow up on the submission by sending email
-to @code{@var{ISSUE_NUMBER}@@debbugs.gnu.org}, where @var{ISSUE_NUMBER}
-is the tracking number (@pxref{Sending a Patch Series}).
+
+Contributors are encouraged to take a moment to set some Git repository options
+(@pxref{Configuring Git}) first, which can improve the readability of patches.
+Seasoned Guix developers may also want to look at the section on commit access
+(@pxref{Commit Access}).
+
+The @email{guix-patches@@gnu.org} mailing list is backed by a Debbugs instance,
+which allows us to keep track of submissions (@pxref{Tracking Bugs and
+Changes}).  Each message sent to that mailing list gets a new tracking number
+assigned; people can then follow up on the submission by sending email to
+@code{@var{ISSUE_NUMBER}@@debbugs.gnu.org}, where @var{ISSUE_NUMBER} is the
+tracking number (@pxref{Sending a Patch Series}).
 
 Please write commit logs in the ChangeLog format (@pxref{Change Logs,,,
 standards, GNU Coding Standards}); you can check the commit history for
@@ -1408,6 +1410,10 @@ Submitting Patches
 what questions a reviewer will ask, and answer those questions in
 advance.
 
+
+@node Patch quality
+@subsection Patch quality
+
 Before submitting a patch that adds or modifies a package definition,
 please run through this check list:
 
@@ -1553,36 +1559,11 @@ Submitting Patches
 
 @end enumerate
 
-When posting a patch to the mailing list, use @samp{[PATCH] @dots{}} as
-a subject, if your patch is to be applied on a branch other than
-@code{master}, say @code{core-updates}, specify it in the subject like
-@samp{[PATCH core-updates] @dots{}}.
-
-You may use your email client or the @command{git send-email} command
-(@pxref{Sending a Patch Series}).  We prefer to get patches in plain
-text messages, either inline or as MIME attachments.  You are advised to
-pay attention if your email client changes anything like line breaks or
-indentation which could potentially break the patches.
-
-Expect some delay when you submit your very first patch to
-@email{guix-patches@@gnu.org}. You have to wait until you get an
-acknowledgement with the assigned tracking number. Future acknowledgements
-should not be delayed.
-
-When a bug is resolved, please close the thread by sending an email to
-@email{@var{ISSUE_NUMBER}-done@@debbugs.gnu.org}.
-
-@menu
-* Configuring Git::
-* Sending a Patch Series::
-* Teams::
-@end menu
 
 @node Configuring Git
 @subsection Configuring Git
 @cindex git configuration
-@cindex @code{git format-patch}
-@cindex @code{git send-email}
+@cindex @code{git config}
 
 If you have not done so already, you may wish to set a name and email
 that will be associated with your commits (@pxref{telling git your name,
@@ -1602,35 +1583,87 @@ Configuring Git
 @file{commit-msg} hook of your own you would like to use with Guix, you
 can place it under the @file{.git/hooks/commit-msg.d/} directory.
 
+
+@node Posting a patch
+@subsection Posting a patch
+@cindex @code{git format-patch}
+
+When posting a patch to the mailing list, use @samp{[PATCH] @dots{}} as a
+subject.  In case your patch is to be applied on a branch other than
+@code{master}, say @code{core-updates}, specify it in the subject like
+@samp{[PATCH core-updates] @dots{}}.
+
+You may use the @command{git send-email} command or your email client to post a
+patch.
+
+Using @command{git send-email} has several advantages, such as automatically
+CC'ing the appropriate teams, avoiding formatting issues, being
+@url{https://git-scm.com/docs/git-send-email#_examples, easy to configure}, and
+convenient to use. Usage is often as simple as @command{git send-email -1} to
+post a single commit.  @xref{Sending a Patch Series} for further details.
+
+Should you still prefer to use your email client, the surest way is to send
+patches produced by @command{git format-patch} as MIME attachments in plain text
+messages.  Using @command{git diff} instead of @command{git format-patch} is not
+advised as it will not include commit metadata.  For a series with multiple
+patches, it is possible to send them as multiple attachments in a single
+message.  Beware that multi-attachment messages will not display correctly on
+the @url{https://issues.guix.gnu.org, Guix issue tracker}, though they will work
+fine with Debbugs.  You may also send patches inline, as each patch file
+generated by @command{git format-patch} is a single valid email message, but
+you'd be advised to pay attention if your email client changes anything like
+line breaks or indentation, which could potentially break the patches.  Finally,
+should you want to notify a team to review your patch, you'll have to figure out
+the appropriate members and CC them manually (@pxref{Teams}).
+
+Expect some delay when you submit your very first patch to
+@email{guix-patches@@gnu.org}.  You have to wait until you get an
+acknowledgement with the assigned tracking number.  Future acknowledgements
+should not be delayed.
+
+When a bug is resolved, please close the thread by sending an email to
+@email{@var{ISSUE_NUMBER}-done@@debbugs.gnu.org}.
+
+
 @node Sending a Patch Series
 @subsection Sending a Patch Series
 @cindex patch series
 @cindex @code{git send-email}
 @cindex @code{git format-patch}
 
-@unnumberedsubsubsec Single Patches
-@anchor{Single Patches}
-The @command{git send-email} command is the best way to send both single
-patches and patch series (@pxref{Multiple Patches}) to the Guix mailing
-list.  Sending patches as email attachments may make them difficult to
-review in some mail clients, and @command{git diff} does not store commit
-metadata.
+The @command{git send-email} command is the best way to send both single patches
+and patch series to the Guix mailing list.
 
 @quotation Note
-The @command{git send-email} command is provided by the @code{send-email}
-output of the @code{git} package, i.e. @code{git:send-email}.
+The @command{git send-email} command is provided by the @code{send-email} output
+of the @code{git} package.  You may install it with @code{guix install
+git:send-email}, and see @url{https://git-scm.com/docs/git-send-email#_examples,
+its documentation} for an example configuration.
 @end quotation
 
-The following command will create a patch email from the latest commit,
-open it in your @var{EDITOR} or @var{VISUAL} for editing, and send it to
-the Guix mailing list to be reviewed and merged.  Assuming you have
-already configured Git according to @xref{Configuring Git}, you can
-simply use:
+@unnumberedsubsubsec Single Commit Patches
+@anchor{Single Commit Patches}
+
+Once you have configured Git (@pxref{Configuring Git}) and @command{git
+send-email}, you can use the following command to create a patch email from the
+latest commit and send it to the Guix mailing list to be reviewed and merged.
+
+@example
+$ git send-email -1
+@end example
+
+If you wish to review the patch before sending, adding the @option{--annotate}
+option will open the patch in your @var{EDITOR} or @var{VISUAL} for editing
+before it gets sent.
 
 @example
 $ git send-email --annotate -1
 @end example
 
+The patch email contains a three-dash separator line after the commit
+message.  You may ``annotate'' the patch with explanatory text by adding
+it under this line.
+
 @quotation Tip
 To add a prefix to the subject of your patch, you may use the
 @option{--subject-prefix} option.  The Guix project uses this to
@@ -1643,17 +1676,12 @@ Sending a Patch Series
 @end example
 @end quotation
 
-The patch email contains a three-dash separator line after the commit
-message.  You may ``annotate'' the patch with explanatory text by adding
-it under this line.  If you do not wish to annotate the email, you may
-drop the @option{--annotate} option.
-
-If you need to send a revised patch, don't resend it like this or send
-a ``fix'' patch to be applied on top of the last one; instead, use
-@command{git commit --amend} or @url{https://git-rebase.io,
-@command{git rebase}} to modify the commit, and use the
-@email{@var{ISSUE_NUMBER}@@debbugs.gnu.org} address and the @option{-v}
-flag with @command{git send-email}.
+If you need to send a revised patch, don't resend it like the above, nor send a
+``fix'' patch to be applied on top of the previous one; instead, use
+@command{git commit --amend} or @url{https://git-rebase.io, @command{git
+rebase}} to modify the commit, then call @command{git send-email} with the
+@email{@var{ISSUE_NUMBER}@@debbugs.gnu.org} address and the @option{-v} flag to
+give the revision a number.
 
 @example
 $ git commit --amend
@@ -1662,47 +1690,44 @@ Sending a Patch Series
 @end example
 
 @quotation Note
-Due to an apparent bug in @command{git send-email},
-@option{-v @var{REVISION}} (with the space) will not work; you
-@emph{must} use @option{-v@var{REVISION}}.
+@command{git send-email} syntax for patch versions is @option{-v@var{REVISION}}.
+Using @option{-v @var{REVISION}} (with a space) will not work.
 @end quotation
 
-You can find out @var{ISSUE_NUMBER} either by searching on the mumi
-interface at @url{https://issues.guix.gnu.org} for the name of your patch or
-reading the acknowledgement email sent automatically by Debbugs in
-reply to incoming bugs and patches, which contains the bug number.
+You can find out @var{ISSUE_NUMBER} either by searching on the Guix issue
+tracker at @url{https://issues.guix.gnu.org} for the name of your patch or by
+reading the acknowledgement email sent automatically by Debbugs in reply to
+incoming bugs and patches, which contains the bug number.
 
 @unnumberedsubsubsec Notifying Teams
 @anchor{Notifying Teams}
 @cindex teams
-If your git checkout has been correctly configured (@pxref{Configuring
-Git}), the @command{git send-email} command will automatically notify
-the appropriate team members, based on the scope of your changes.  This
-relies on the @file{etc/teams.scm} script, which can also be invoked
-manually if you do not use the preferred @command{git send-email}
-command to submit patches.  To list the available actions of the script,
-you can invoke it via the @command{etc/teams.scm help} command.  For
-more information regarding teams, @pxref{Teams}.
+If your git checkout has been correctly configured (@pxref{Configuring Git}),
+the @command{git send-email} command will automatically notify the appropriate
+team members, based on the scope of your changes.  This relies on the
+@file{etc/teams.scm} script, which can also be invoked manually if you do not
+use the preferred @command{git send-email} command to submit patches.  For more
+information regarding teams and @file{etc/teams.scm}, @pxref{Teams}.
 
 @quotation Note
-On foreign distros, you might have to use @command{./pre-inst-env git
-send-email} for @file{etc/teams.scm} to work.
+When using Guix as a package manager on foreign distros, you might have to use
+@command{./pre-inst-env git send-email} for @file{etc/teams.scm} to work.
 @end quotation
 
-@unnumberedsubsubsec Multiple Patches
-@anchor{Multiple Patches}
+@unnumberedsubsubsec Multiple Commit Patches
+@anchor{Multiple Commit Patches}
 @cindex cover letter
-While @command{git send-email} alone will suffice for a single
-patch, an unfortunate flaw in Debbugs means you need to be more
-careful when sending multiple patches: if you send them all to the
-@email{guix-patches@@gnu.org} address, a new issue will be created
-for each patch!
-
-When sending a series of patches, it's best to send a Git ``cover
-letter'' first, to give reviewers an overview of the patch series.
-We can create a directory called @file{outgoing} containing both
-our patch series and a cover letter called @file{0000-cover-letter.patch}
-with @command{git format-patch}.
+While @command{git send-email} alone will suffice for a single patch, you need
+to be more careful when sending multiple patches: if you send them all to the
+@email{guix-patches@@gnu.org} address, a new issue will be created for each
+patch!
+
+When sending a series of patches, it's best to send a Git ``cover letter''
+first, to give reviewers an overview of the patch series and create a single
+issue to send them to.  We can create a directory called @file{outgoing}
+containing both a cover letter called @file{0000-cover-letter.patch} and a patch
+series for the @var{NUMBER_COMMITS} last commits with @command{git
+format-patch}.
 
 @example
 $ git format-patch -@var{NUMBER_COMMITS} -o outgoing \
@@ -1710,29 +1735,32 @@ Sending a Patch Series
 @end example
 
 We can now send @emph{just} the cover letter to the
-@email{guix-patches@@gnu.org} address, which will create an issue
-that we can send the rest of the patches to.
+@email{guix-patches@@gnu.org} address, thus creating an issue to which we can
+send the patches.
 
 @example
 $ git send-email outgoing/0000-cover-letter.patch --annotate
 $ rm outgoing/0000-cover-letter.patch # we don't want to resend it!
 @end example
 
-Ensure you edit the email to add an appropriate subject line and
-blurb before sending it.  Note the automatically generated shortlog
-and diffstat below the blurb.
+The command will open the cover letter for editing so you can add an appropriate
+subject line and blurb before sending it.  Note the automatically generated
+shortlog and diffstat below the blurb.
 
-Once the Debbugs mailer has replied to your cover letter email, you
-can send the actual patches to the newly-created issue address.
+Once the Debbugs mailer has replied to your cover letter email, with the
+@var{ISSUE_NUMBER} in the reply, you can send the actual patches to the
+newly-created issue address.
 
 @example
 $ git send-email outgoing/*.patch --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org
 $ rm -rf outgoing # we don't need these anymore
 @end example
 
+And you're done!
+
 Thankfully, this @command{git format-patch} dance is not necessary
 to send an amended patch series, since an issue already exists for
-the patchset.
+the patchset.  Calling @command{git send-email} directly will do.
 
 @example
 $ git send-email -@var{NUMBER_COMMITS} -v@var{REVISION} \
@@ -1741,45 +1769,55 @@ Sending a Patch Series
 
 If need be, you may use @option{--cover-letter --annotate} to send
 another cover letter, e.g. for explaining what's changed since the last
-revision, and these changes are necessary.
+revision, and why these changes are necessary.
 
 @node Teams
 @subsection Teams
 @cindex teams
 
-There are several teams mentoring different parts of the Guix source
-code.  To list all those teams, you can run from a Guix checkout:
+There are several teams mentoring different parts of the Guix source code.  The
+script @file{etc/teams.scm} provides information about them.
+
+To list all teams with their members and the files under their scope, you can
+run from a Guix checkout:
 
 @example
 $ ./etc/teams.scm list-teams
+@end example
+
+To list the scope and members of a single team, for example the team `mentors'
+(which has no file scope):
+
+@example
+$ ./etc/teams.scm show mentors
 id: mentors
 name: Mentors
 description: A group of mentors who chaperone contributions by newcomers.
 members:
 + Christopher Baines <mail@@cbaines.net>
-+ Ricardo Wurmus <rekado@@elephly.net>
++ Ludovic Courtès <ludo@@gnu.org>
 + Mathieu Othacehe <othacehe@@gnu.org>
++ Ricardo Wurmus <rekado@@elephly.net>
 + jgart <jgart@@dismail.de>
-+ Ludovic Courtès <ludo@@gnu.org>
-@dots{}
 @end example
 
-You can run the following command to have the @code{Mentors} team put in
-CC of a patch series:
+@file{etc/teams.scm} can also infer the appropriate team or teams to notify
+about a patch series, and output option strings to be used with @command{git
+send-email} as well as @command{git format-patch}.  If Git was properly
+configured (@pxref{Configuring Git}), this is handled automatically by
+@command{git send-email} as explained in @ref{Notifying Teams}.
+
+As an example, you can run the following command to have the @code{Mentors} team
+put in CC of a seires of patch files to be sent with @command{git send-email}:
 
 @example
 $ git send-email --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org \
   --header-cmd='etc/teams.scm cc-mentors-header-cmd' *.patch
 @end example
 
-The appropriate team or teams can also be inferred from the modified
-files.  For instance, if you want to send the two latest commits of the
-current Git repository to review, you can run:
+To list the available actions of the script, you can invoke it via the
+@file{etc/teams.scm help} command.
 
-@example
-$ guix shell -D guix
-[env]$ git send-email --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org -2
-@end example
 
 @node Tracking Bugs and Changes
 @section Tracking Bugs and Changes
@@ -2215,7 +2253,7 @@ Commit Access
 
 To avoid accidentally pushing unsigned or signed with the wrong key
 commits to Savannah, make sure to configure Git according to
-@xref{Configuring Git}.
+@ref{Configuring Git}.
 
 @subsection Commit Policy
 
diff --git a/doc/guix.texi b/doc/guix.texi
index 395545bed7..b2b7557742 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -7847,7 +7847,7 @@ Defining Packages
 @code{guix download} (@pxref{Invoking guix download}) and @code{guix
 hash} (@pxref{Invoking guix hash}).
 
-@cindex patches
+@cindex patches, for packages
 When needed, the @code{origin} form can also have a @code{patches} field
 listing patches to be applied, and a @code{snippet} field giving a
 Scheme expression to modify the source code.
@@ -8576,7 +8576,7 @@ Defining Package Variants
 and in your own package collection
 (@pxref{Creating a Channel}), among others!
 
-@cindex inherit, for package definitions
+@cindex inherit, for packages
 As discussed earlier, packages are first-class objects in the Scheme
 language.  The @code{(guix packages)} module provides the @code{package}
 construct to define new package objects (@pxref{package Reference}).

base-commit: c4fa3e945eee84f0459760f3ba8232dec49bd1ba
-- 
2.41.0