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

[Junio C Hamano <gitster@pobox.com>]

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.

Thanks.