bug#58813: [PATCH] doc: Document how to use Patman for patches submission.

[Maxim Cournoyer]

Hi Ludovic,

Ludovic Courtès <ludo@gnu.org> writes:

> Hi,
>
> Maxim Cournoyer <maxim.cournoyer@gmail.com> skribis:
>
>> Fixes <https://issues.guix.gnu.org/58813>.
>
> It’s only tangentially related, no?

It's not totally a tangent, because it removes examples which do not
work, and replace them with ones that do work, and recommend a tool that
can do what the previous shell command substitution failed to do
correctly (due to shell parsing rules).

>> * doc/contributing.texi (Sending a Patch Series): Mention Patman.  Adjust the
>> examples to no longer showcase broken command substitutions.  Add a section
>> about how to use Patman, with examples.
>
> I’m not convinced we’d want to advocate for yet another tool.  I feel
> like this would make patch submission guidelines even more complex, or
> at least look more complex.
>
> Also, how many of the ~40 committers would be able to provide guidance
> with patman?  That shouldn’t be the only criterion, but it certainly is
> an important one.

Since it's just documented as another tool on top, I don't think this
matters too much (it can be adopted or not).  It's also a very simple
tool, which is more often than not invoked as simply 'patman' or 'patman
-n' (for dry-run).

I've also discovered about '--cc-cmd', which could be used with the
recently introduced get-maintainer mode (which was added for patman
support); it can be used like this:

--8<---------------cut here---------------start------------->8---
git send-email --cc-cmd='etc/teams.scm get-maintainer' --dry-run -1
--8<---------------cut here---------------end--------------->8---

It does the same thing as the copy/pasting of the output of

--8<---------------cut here---------------start------------->8---
etc/teams.scm cc-members HEAD^ HEAD
--8<---------------cut here---------------end--------------->8---

To the git send-email command, but with one difference: it uses '--cc'
for the email addresses instead of the nicer --add-header="X-Debbugs-Cc:
mail@example.org" ones.  The later is best because when initially
sending the message to Debbugs, there's no bug # known yet, and the
receivers would be left to guess and perhaps even reply erroneously to
guix-patches@gnu.org and create a new ticket.

For this reason, I'm toying with the idea of contributing a "--x-cmd"
option to git send-email, which would be a script that outputs arbitrary
git send-email options to add to its command line.

To be continued...

-- 
Thanks,
Maxim