[bug#58648] [PATCH 1/1] doc: contributing: Expand "Sending a Patch Series".

[zimoun <zimon.toutoune@gmail.com>]

Hi,

Minor suggestions, for what they are worth. :-)


On mer., 19 oct. 2022 at 23:00, "\( via Guix-patches" via <guix-patches@gnu.org> wrote:

> +The @code{git send-email} and @code{git format-patch} commands allow you
> +to send your commits in email form to a mailing list, to be reviewed and
> +applied, and they are the recommended way to submit contributions to Guix.
> +When you send the first revision of a patch series, it's best to use
> +@code{git format-patch --cover-letter}.


> +@example
> +$ git format-patch -$N -o outgoing --cover-letter
> +@end example

Here…

> +
> +@quotation Note
> +The @code{git send-email} command is provided by the @code{send-email}
> +output of the @code{git} package, i.e. @code{git:send-email}.
> +@end quotation
> +
> +This command makes patches out of the last @var{N} commits, and writes
> +them to @code{.patch} files in @code{outgoing/}, along with an automatically
> +generated cover letter.  We can then send the cover letter to the Guix
> +mailing list.

…or in these explanations, I would also suggest the option ’--base’; as
recommended by item #1 in subsection «Submitting Patches».


[...]

> +At some point, the Debbugs mailer will reply to your cover letter mail
> +with an acknowledgement, which contains the issue number of your patchset.
> +You should now send the rest of the patches to this issue thread, using
> +the @code{@var{ISSUE_NUMBER}@@debbugs.gnu.org} address.

I agree that ISSUE_NUMBER is a better name than NNN or else.  Therefore,
maybe it could be worth to also tweak it in the section Teams.


[...]

> +The use of the @code{etc/teams.scm} script to notify the appropriate team
> +members (@pxref{Teams}) is recommended when submitting patches, to maximize
> +the chances of your patch series being reviewed quickly.

I would advertise about Teams early in this section.  Maybe in the first
paragraph.



Cheers,
simon