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

From: Junio C Hamano <gitster@pobox.com>
Date: May 5, 2025, 19:20 UTC
Message-ID: <xmqqv7qeooed.fsf@gitster.g>
In-Reply-To: <PN3PR01MB9597E545331A9BBF088329EBB88E2@PN3PR01MB9597.INDPRD01.PROD.OUTLOOK.COM>

Aditya Garg <gargaditya08@live.com> writes:

Show 5 quoted lines

> 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.

Show 12 quoted lines

> +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.

Thanks.