Re: [PATCH v2 2/3] docs: improve send-email documentation

> On 6 May 2025, at 12:50 AM, Junio C Hamano <gitster@pobox.com> wrote:
> 
> Aditya Garg <gargaditya08@live.com> writes:
> 
>> This commit does the following changes to the send email doc:
>> 
>> 1. Added examples to use OAuth2.0 with Gmail and Outlook.
>> 2. Improved examples to send patches using git send-email
>> 3. Added links of credential helpers for Gmail and Outlook
> 
> The usual way to compose a log message of this project is to
> 
> - Give an observation on how the current system works in the present
>   tense (so no need to say "Currently X is Y", just "X is Y"), and
>   discuss what you perceive as a problem in it.
> 
> - Propose a solution (optional---often, problem description
>   trivially leads to an obvious solution in reader's minds).
> 
> - Give commands to the codebase to "become like so".
> 
> in this order.  Don't throw a bulleted list at readers without
> preparing them by explaining what problem you are solving and why
> such a solution is needed.
> 
>> +SENDING PATCHES
>> +---------------
>> +The following examples can be used to have a basic idea on how to send patches
>> +to a mailing list:
>> +
>> +If you want to send a single patch, run:
>> +
>> +    $ git send-email --to="mailinglist@example.org" HEAD~1
>> ...
>> -    $ git format-patch --cover-letter -M origin/master -o outgoing/
>> -    $ edit outgoing/0000-*
>> -    $ git send-email outgoing/*
> 
> All good intentions to improve the documentation, but loss of these
> lines is very much lamentable, especially the fact that these
> original instructions were written to encourage to run format-patch
> and send-email as separate steps, with proofreading and final
> copy-editing step in between.
> 
> It means the author has a chance to spend more time and care to help
> recipients read their patches more smoothly with fewer typoes and
> improved explanations.
> 
> Running "git send-email" with the revision range to run the "git
> format-patch" command is often an anti-pattern, especially for
> unexperienced people who are still learning from the examples in the
> documentation.  Please do not unnecessarily promote the use of it.