bug#58813: can't substitute etc/teams.scm command as doc suggests

bug#58813: can't substitute etc/teams.scm command as doc suggests

[Maxim Cournoyer]

Hi,

Today, I tried;

--8<---------------cut here---------------start------------->8---
$ git send-email --to=guix-patches@gnu.org \
  $(./etc/teams.scm cc-members origin/master HEAD) 0000-cover-letter.patch
fatal: ambiguous argument 'some.email@redacted.com"': unknown revision or path not in the working tree.
Use '--' to separate paths from revisions, like this:
'git <command> [<revision>...] -- [<file>...]'
format-patch -o /tmp/pFSRbRNNoU --add-header="X-Debbugs-Cc: redacted@gmail.com" --add-header="X-Debbugs-Cc: redacted@email" [...]: command returned error: 128

$ ./etc/teams.scm cc-members origin/master HEAD
--add-header="X-Debbugs-Cc: redacted@email" --add-header="X-Debbugs-Cc: redacted@email" ...
--8<---------------cut here---------------end--------------->8---

You can see the command fails; this is because when using Bash command
substitution $(), the quotes in the result are not interpreted and are
thus part of the value (literals), which then gets split on white space.

As a quick hacky fix,  I tried removing the space and double quotes
like:

modified   etc/teams.scm.in
@@ -514,7 +514,7 @@ (define (cc . teams)
   "Return arguments for `git send-email' to notify the members of the given
 TEAMS when a patch is received by Debbugs."
   (format #true
-          "~{--add-header=\"X-Debbugs-Cc: ~a\"~^ ~}"
+          "~{--add-header=X-Debbugs-Cc:~a~^ ~}"
           (map person-email
                (delete-duplicates (append-map team-members teams) equal?))))

and sent a patch with that command:

git send-email --to=guix-patches@gnu.org \
  $(./etc/teams.scm cc-members origin/master HEAD 0000-cover-letter.patch

It created https://issues.guix.gnu.org/58812 with it, but I don't see
any of the X-Debbugs-Cc headers.  Mmmh.

-- 
Thanks,
Maxim

bug#58813: can't substitute etc/teams.scm command as doc suggests

[Liliana Marie Prikler]

Am Mittwoch, dem 26.10.2022 um 23:50 -0400 schrieb Maxim Cournoyer:
> Hi,
> 
> Today, I tried;
> 
> --8<---------------cut here---------------start------------->8---
> $ git send-email --to=guix-patches@gnu.org \
>   $(./etc/teams.scm cc-members origin/master HEAD) 0000-cover-
> letter.patch
> fatal: ambiguous argument 'some.email@redacted.com"': unknown
> revision or path not in the working tree.
> Use '--' to separate paths from revisions, like this:
> 'git <command> [<revision>...] -- [<file>...]'
> format-patch -o /tmp/pFSRbRNNoU --add-header="X-Debbugs-Cc:
> redacted@gmail.com" --add-header="X-Debbugs-Cc: redacted@email"
> [...]: command returned error: 128
> 
> $ ./etc/teams.scm cc-members origin/master HEAD
> --add-header="X-Debbugs-Cc: redacted@email" --add-header="X-Debbugs-
> Cc: redacted@email" ...
> --8<---------------cut here---------------end--------------->8---
> 
> You can see the command fails; this is because when using Bash
> command substitution $(), the quotes in the result are not
> interpreted and are thus part of the value (literals), which then
> gets split on white space.
> 
> As a quick hacky fix,  I tried removing the space and double quotes
> like:
> 
> modified   etc/teams.scm.in
> @@ -514,7 +514,7 @@ (define (cc . teams)
>    "Return arguments for `git send-email' to notify the members of
> the given
>  TEAMS when a patch is received by Debbugs."
>    (format #true
> -          "~{--add-header=\"X-Debbugs-Cc: ~a\"~^ ~}"
> +          "~{--add-header=X-Debbugs-Cc:~a~^ ~}"
>            (map person-email
>                 (delete-duplicates (append-map team-members teams)
> equal?))))
> 
> and sent a patch with that command:
> 
> git send-email --to=guix-patches@gnu.org \
>   $(./etc/teams.scm cc-members origin/master HEAD 0000-cover-
> letter.patch
> 
> It created https://issues.guix.gnu.org/58812 with it, but I don't see
> any of the X-Debbugs-Cc headers.  Mmmh.
Note that the existing etc/teams also assumes there are no funny
characters in the quote.  So it's susceptible to good ol' bobby tables.

Could we, instead of outputting a command, make it so that we can pass
an already formatted patch and etc/teams rewrites it?

Cheers

bug#58813: can't substitute etc/teams.scm command as doc suggests

[Maxim Cournoyer]

Hi,

Liliana Marie Prikler <liliana.prikler@gmail.com> writes:

> Am Mittwoch, dem 26.10.2022 um 23:50 -0400 schrieb Maxim Cournoyer:
>> Hi,
>> 
>> Today, I tried;
>> 
>> --8<---------------cut here---------------start------------->8---
>> $ git send-email --to=guix-patches@gnu.org \
>>   $(./etc/teams.scm cc-members origin/master HEAD) 0000-cover-
>> letter.patch
>> fatal: ambiguous argument 'some.email@redacted.com"': unknown
>> revision or path not in the working tree.
>> Use '--' to separate paths from revisions, like this:
>> 'git <command> [<revision>...] -- [<file>...]'
>> format-patch -o /tmp/pFSRbRNNoU --add-header="X-Debbugs-Cc:
>> redacted@gmail.com" --add-header="X-Debbugs-Cc: redacted@email"
>> [...]: command returned error: 128
>> 
>> $ ./etc/teams.scm cc-members origin/master HEAD
>> --add-header="X-Debbugs-Cc: redacted@email" --add-header="X-Debbugs-
>> Cc: redacted@email" ...
>> --8<---------------cut here---------------end--------------->8---
>> 
>> You can see the command fails; this is because when using Bash
>> command substitution $(), the quotes in the result are not
>> interpreted and are thus part of the value (literals), which then
>> gets split on white space.
>> 
>> As a quick hacky fix,  I tried removing the space and double quotes
>> like:
>> 
>> modified   etc/teams.scm.in
>> @@ -514,7 +514,7 @@ (define (cc . teams)
>>    "Return arguments for `git send-email' to notify the members of
>> the given
>>  TEAMS when a patch is received by Debbugs."
>>    (format #true
>> -          "~{--add-header=\"X-Debbugs-Cc: ~a\"~^ ~}"
>> +          "~{--add-header=X-Debbugs-Cc:~a~^ ~}"
>>            (map person-email
>>                 (delete-duplicates (append-map team-members teams)
>> equal?))))
>> 
>> and sent a patch with that command:
>> 
>> git send-email --to=guix-patches@gnu.org \
>>   $(./etc/teams.scm cc-members origin/master HEAD 0000-cover-
>> letter.patch
>> 
>> It created https://issues.guix.gnu.org/58812 with it, but I don't see
>> any of the X-Debbugs-Cc headers.  Mmmh.
> Note that the existing etc/teams also assumes there are no funny
> characters in the quote.  So it's susceptible to good ol' bobby tables.
>
> Could we, instead of outputting a command, make it so that we can pass
> an already formatted patch and etc/teams rewrites it?

The solution suggested to me in #bash would be to turn etc/teams.scm
into a git wrapper, that could invoke git with all the arguments at once
(allowing people to pass arguments themselves).  I'm told the git
completion could be hooked to such script so that users can still enjoy
git tab-completion when using etc/teams.scm, although I haven't
researched how that'd all work.

A similar idea proposed by selckin on #git would be to have our
etc/teams.scm script receive the complete git command, and append the
args to it itself (and invoke it), like so:

./etc/teams.scm cc mentors -- git send-email --to XXX@debbugs.gnu.org *.patch

-- 
Thanks,
Maxim

bug#58813: can't substitute etc/teams.scm command as doc suggests

[Liliana Marie Prikler]

Am Donnerstag, dem 27.10.2022 um 08:40 -0400 schrieb Maxim Cournoyer:
> Hi,
> 
> Liliana Marie Prikler <liliana.prikler@gmail.com> writes:
> 
> > Am Mittwoch, dem 26.10.2022 um 23:50 -0400 schrieb Maxim Cournoyer:
> > > Hi,
> > > 
> > > Today, I tried;
> > > 
> > > --8<---------------cut here---------------start------------->8---
> > > $ git send-email --to=guix-patches@gnu.org \
> > >   $(./etc/teams.scm cc-members origin/master HEAD) 0000-cover-
> > > letter.patch
> > > fatal: ambiguous argument 'some.email@redacted.com"': unknown
> > > revision or path not in the working tree.
> > > Use '--' to separate paths from revisions, like this:
> > > 'git <command> [<revision>...] -- [<file>...]'
> > > format-patch -o /tmp/pFSRbRNNoU --add-header="X-Debbugs-Cc:
> > > redacted@gmail.com" --add-header="X-Debbugs-Cc: redacted@email"
> > > [...]: command returned error: 128
> > > 
> > > $ ./etc/teams.scm cc-members origin/master HEAD
> > > --add-header="X-Debbugs-Cc: redacted@email" --add-header="X-
> > > Debbugs-
> > > Cc: redacted@email" ...
> > > --8<---------------cut here---------------end--------------->8---
> > > 
> > > You can see the command fails; this is because when using Bash
> > > command substitution $(), the quotes in the result are not
> > > interpreted and are thus part of the value (literals), which then
> > > gets split on white space.
> > > 
> > > As a quick hacky fix,  I tried removing the space and double
> > > quotes
> > > like:
> > > 
> > > modified   etc/teams.scm.in
> > > @@ -514,7 +514,7 @@ (define (cc . teams)
> > >    "Return arguments for `git send-email' to notify the members
> > > of
> > > the given
> > >  TEAMS when a patch is received by Debbugs."
> > >    (format #true
> > > -          "~{--add-header=\"X-Debbugs-Cc: ~a\"~^ ~}"
> > > +          "~{--add-header=X-Debbugs-Cc:~a~^ ~}"
> > >            (map person-email
> > >                 (delete-duplicates (append-map team-members
> > > teams)
> > > equal?))))
> > > 
> > > and sent a patch with that command:
> > > 
> > > git send-email --to=guix-patches@gnu.org \
> > >   $(./etc/teams.scm cc-members origin/master HEAD 0000-cover-
> > > letter.patch
> > > 
> > > It created https://issues.guix.gnu.org/58812 with it, but I don't
> > > see
> > > any of the X-Debbugs-Cc headers.  Mmmh.
> > Note that the existing etc/teams also assumes there are no funny
> > characters in the quote.  So it's susceptible to good ol' bobby
> > tables.
> > 
> > Could we, instead of outputting a command, make it so that we can
> > pass
> > an already formatted patch and etc/teams rewrites it?
> 
> The solution suggested to me in #bash would be to turn etc/teams.scm
> into a git wrapper, that could invoke git with all the arguments at
> once (allowing people to pass arguments themselves).  I'm told the
> git completion could be hooked to such script so that users can still
> enjoy git tab-completion when using etc/teams.scm, although I haven't
> researched how that'd all work.
> 
> A similar idea proposed by selckin on #git would be to have our
> etc/teams.scm script receive the complete git command, and append the
> args to it itself (and invoke it), like so:
> 
> ./etc/teams.scm cc mentors -- git send-email --to
> XXX@debbugs.gnu.org *.patch
I think we should go with the former and implement a proper "guix send-
email" ;)

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

[Maxim Cournoyer]

Fixes <https://issues.guix.gnu.org/58813>.

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

---

 doc/contributing.texi | 119 ++++++++++++++++++++++++++++++++++++++----
 doc/guix.texi         |   2 +-
 2 files changed, 110 insertions(+), 11 deletions(-)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index c436bc4a31..2a12dffefe 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -1416,12 +1416,19 @@ git config --local sendemail.thread no
 @cindex @code{git format-patch}
 
 @unnumberedsubsubsec Single Patches
-@anchor{Single Patches}
-The @command{git send-email} command is the best way to send both single
-patches and patch series (@pxref{Multiple Patches}) to the Guix mailing
-list.  Sending patches as email attachments may make them difficult to
-review in some mail clients, and @command{git diff} does not store commit
-metadata.
+@cindex patman patch manager
+@cindex patch management, via patman
+@anchor{Single Patches} The @command{git send-email} command is the best
+way to send both single patches and patch series (@pxref{Multiple
+Patches}) to the Guix mailing list.  Sending patches as email
+attachments may make them difficult to review in some mail clients, and
+@command{git diff} does not store commit metadata.  If you want
+something a bit higher level than @command{git send-email} to organize
+your patch submissions and take care of its various options for you, you
+may want to try the @command{patman} command, from the eponymous
+package.  Patman's help can be accessed via @samp{patman -H} or as an
+Info manual after installing the @code{u-boot-documentation} package
+(@pxref{Patman patch manager,,,u-boot,The U-Boot Documentation}).
 
 @quotation Note
 The @command{git send-email} command is provided by the @code{send-email}
@@ -1521,7 +1528,7 @@ that we can send the rest of the patches to.
 @example
 $ git send-email outgoing/0000-cover-letter.patch -a \
       --to=guix-patches@@gnu.org \
-      $(etc/teams.scm cc-members ...)
+      --cc=team-member1@@example.org --cc=team-member2@@example.org ...
 $ rm outgoing/0000-cover-letter.patch # we don't want to resend it!
 @end example
 
@@ -1535,7 +1542,7 @@ can send the actual patches to the newly-created issue address.
 @example
 $ git send-email outgoing/*.patch \
       --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org \
-      $(etc/teams.scm cc-members ...)
+      --cc=team-member1@@example.org --cc=team-member2@@example.org ...
 $ rm -rf outgoing # we don't need these anymore
 @end example
 
@@ -1578,18 +1585,110 @@ You can run the following command to have the @code{Mentors} team put in
 CC of a patch series:
 
 @example
-$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org $(./etc/teams.scm cc mentors) *.patch
+$ ./etc/teams.scm cc mentors
 @end example
 
+then note the @var{output} of the script.
+
+@example
+$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org @var{output} *.patch
+@end example
+
+Taking care to manually splice the @var{output} of the
+@file{etc/teams.scm} script into the command.
+
 The appropriate team or teams can also be inferred from the modified
 files.  For instance, if you want to send the two latest commits of the
 current Git repository to review, you can run:
 
 @example
 $ guix shell -D guix
-[env]$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org $(./etc/teams.scm cc-members HEAD~2 HEAD) *.patch
+[env]$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org @var{output} *.patch
 @end example
 
+@cindex patman, usage example
+As manually stitching the output of the @file{etc/teams.scm} script in
+the @command{git send-email} command can get tedious; you may prefer to
+use Patman to automate this for you.  Its necessary basic configuration
+is already found at the root of the Guix repository, in the
+@file{.patman} file.  Another useful bit to have is a default
+destination for the @command{git send-email} command.  You can specify
+it in your repository-local Guix @file{.git/config} file with:
+
+@example
+[sendemail]
+        to = guix-patches@@gnu.org
+@end example
+
+To send a long series to Debbugs, the patches can be written to the
+current directory with:
+
+@example
+patman -n
+@end example
+
+The first patch should then be sent using @samp{git send-email
+0000-cover-letter.patch}, as explained earlier (@pxref{Multiple
+Patches}).
+
+After Debbugs has issued a unique bug email in reply to that initial
+patch submission, e.g. @email{NNNNN@@debbugs.gnu.org}, you can save this
+information into the top commit of your patch series (it doesn't matter
+which, but it's more convenient to amend it later when it's at the top)
+like so, via the Patman-specific @code{Series-to} git message tag:
+
+@example
+gnu: Add foo.
+
+* gnu/packages/dummy.scm: Add foo.
+
+Series-to: NNNNN@@debbugs.gnu.org
+@end example
+
+You can then send your series to that address with the right people
+automatically added in CC by simply issuing:
+
+@example
+patman
+@end example
+
+After addressing the first round of review comments, you can annotate a
+v2 patch series by adding these Patman-specific git message tags:
+
+@example
+gnu: Add foo.
+
+* gnu/packages/dummy.scm: Add foo.
+
+Series-to: NNNNN@@debbugs.gnu.org
+Series-version: 2
+Series-changes: 2
+- Factorized X into Y and Z
+
+@end example
+
+The @command{patman} command will then take care to automate the right
+@code{git send-email} command and produce patch annotations useful for
+the reviewers.
+
+After the review is complete, if you are the one merging your own
+changes, you should take care to strip any Patman git message tags.
+This can be done by writing the patches to the current directory with:
+
+@example
+patman -n
+@end example
+
+and then applying them to the main branch with:
+
+@example
+git am *.patch
+@end example
+
+For more information, run @samp{patman -H} or read its info manual,
+which can be installed with the @code{u-boot-documentation} package
+(@pxref{Patman patch manager,,,u-boot,The U-Boot Documentation}).
+
 @node Tracking Bugs and Patches
 @section Tracking Bugs and Patches
 
diff --git a/doc/guix.texi b/doc/guix.texi
index a7ef00f421..5a4900d7cf 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -49,7 +49,7 @@ Copyright @copyright{} 2017 humanitiesNerd@*
 Copyright @copyright{} 2017, 2021 Christine Lemmer-Webber@*
 Copyright @copyright{} 2017, 2018, 2019, 2020, 2021, 2022 Marius Bakke@*
 Copyright @copyright{} 2017, 2019, 2020, 2022 Hartmut Goebel@*
-Copyright @copyright{} 2017, 2019, 2020, 2021, 2022 Maxim Cournoyer@*
+Copyright @copyright{} 2017, 2019, 2020, 2021, 2022, 2023 Maxim Cournoyer@*
 Copyright @copyright{} 2017–2022 Tobias Geerinckx-Rice@*
 Copyright @copyright{} 2017 George Clemmer@*
 Copyright @copyright{} 2017 Andy Wingo@*

base-commit: 9a2cf9ef0a9ece9aa0dcb24a31fe0c313d06988f
-- 
2.39.1

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

[Liliana Marie Prikler]

Am Samstag, dem 25.02.2023 um 22:55 -0500 schrieb Maxim Cournoyer:
> Fixes <https://issues.guix.gnu.org/58813>.
> 
> * 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.
It looks like 61797 addresses the broken command – I'd still like the
patman changes, but perhaps we can reduce the impact?

Cheers

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

[Maxim Cournoyer]

Hi Liliana,

Liliana Marie Prikler <liliana.prikler@gmail.com> writes:

> Am Samstag, dem 25.02.2023 um 22:55 -0500 schrieb Maxim Cournoyer:
>> Fixes <https://issues.guix.gnu.org/58813>.
>> 
>> * 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.
> It looks like 61797 addresses the broken command – I'd still like the
> patman changes, but perhaps we can reduce the impact?

It seems Tobias realized that change wouldn't be sufficient to fix the
underlying problem, and closed it.

-- 
Thanks,
Maxim

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

[Tobias Geerinckx-Rice via Bug reports for GNU Guix]

Hi,

> teams.scm

I closed the bug-that-didn't-fix, but that still leaves a git-specific command that doesn't actually facilitate git.¹

I guess salvaging 'teams.scm cc' into a generic 'Cc:' header generator makes some sense?  Without the $() use case.

Otherwise: shall we simply remove it?

Kind regards,

T G-R

Sent on the go.  Excuse or enjoy my brevity.

1: Code golfing bash snippets that make it 'work' doesn't count, but it's fun.

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

[Maxim Cournoyer]

Hello,

Tobias Geerinckx-Rice <me@tobias.gr> writes:

> Hi,
>
>> teams.scm
>
> I closed the bug-that-didn't-fix, but that still leaves a git-specific
> command that doesn't actually facilitate git.¹
>
> I guess salvaging 'teams.scm cc' into a generic 'Cc:' header generator
> makes some sense?  Without the $() use case.
>
> Otherwise: shall we simply remove it?

I think I'd leave it; people can still use it to manually copy-paste its
output into their command.  That's not great, but it's better than
nothing.

-- 
Thanks,
Maxim

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

[Ludovic Courtès]

Hi,

Maxim Cournoyer <maxim.cournoyer@gmail.com> skribis:

> Fixes <https://issues.guix.gnu.org/58813>.

It’s only tangentially related, no?

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

Thanks,
Ludo’.

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

[Liliana Marie Prikler]

Am Freitag, dem 03.03.2023 um 10:54 +0100 schrieb Ludovic Courtès:
> Hi,
> 
> Maxim Cournoyer <maxim.cournoyer@gmail.com> skribis:
> 
> > Fixes <https://issues.guix.gnu.org/58813>.
> 
> It’s only tangentially related, no?
> 
> > * 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.
I do think it'd be fine to have more options (in a "use what you find
convenient" way), but as-is this patch replaces one imperfect tool with
one where:

> [H]ow many of the ~40 committers would be able to provide guidance
> with patman?  
I'm not one of them :(

> That shouldn’t be the only criterion, but it certainly is an
> important one.
I think an important criterion should be what aspiring committers can
expect when they follow the advice as written.  Compare and contrast
'guix style', where committers often have to point out its flaws.

Cheers

bug#58813: ‘guix style’ flaws

[Ludovic Courtès]

Liliana Marie Prikler <liliana.prikler@gmail.com> skribis:

> Compare and contrast
> 'guix style', where committers often have to point out its flaws.

Hi!  Drifting off-topic, but: I’d really like people to report specific
issues to bug-guix so we can act on them and reach the point where the
tool’s output is good 99% of the time.

Ludo’.

bug#58813: ‘guix style’ flaws

[Maxim Cournoyer]

Hi Ludo,

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

> Liliana Marie Prikler <liliana.prikler@gmail.com> skribis:
>
>> Compare and contrast
>> 'guix style', where committers often have to point out its flaws.
>
> Hi!  Drifting off-topic, but: I’d really like people to report specific
> issues to bug-guix so we can act on them and reach the point where the
> tool’s output is good 99% of the time.

See #61013 :-).

-- 
Thanks,
Maxim

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

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

[Ludovic Courtès]

Hi,

Maxim Cournoyer <maxim.cournoyer@gmail.com> skribis:

> 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:
>
> git send-email --cc-cmd='etc/teams.scm get-maintainer' --dry-run -1

Nice!  But yeah, would be nicer if it could use X-Debbugs-Cc.

Perhaps we can still change the manual to recommend that followed by
“sed -i *.patch -es/^Cc/X-Debbugs-Cc/”?

Very low-tech but better than the status quo.  WDYT?

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

That’d be perfect!

Ludo’.

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

[Maxim Cournoyer]

Hi Ludo,

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

> Hi,
>
> Maxim Cournoyer <maxim.cournoyer@gmail.com> skribis:
>
>> 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:
>>
>> git send-email --cc-cmd='etc/teams.scm get-maintainer' --dry-run -1
>
> Nice!  But yeah, would be nicer if it could use X-Debbugs-Cc.
>
> Perhaps we can still change the manual to recommend that followed by
> “sed -i *.patch -es/^Cc/X-Debbugs-Cc/”?
>
> Very low-tech but better than the status quo.  WDYT?
>
>> 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.
>
> That’d be perfect!

Good, I haven't gotten any feedback from the #git folks, so I guess I'll
forge ahead and see what comments they have about the implementation.
It might be some time before I can hack on this.

To be continued!

-- 
Thanks,
Maxim

bug#58813: [PATCH 0/5] Fix teams.scm by use of a new --header-cmd git send-email option.

[Maxim Cournoyer]

Hello,

This adds a brand new '--header-cmd' option, to git send-email, which
can then be used to fix the issues reported against teams.scm in
https://issues.guix.gnu.org/58813.

The configuration of Git is also automated, which should make
everyone's life easier (and helps keeping the doc focused).

Thanks,

Maxim Cournoyer (5):
  gnu: git: Apply patch adding the --header-cmd feature.
  teams: Add 'cc-members-header-cmd' action.
  teams: Add a configure-git action.
  teams: Add a 'cc-mentors-header-cmd' action.
  doc: Simplify contributing section by automating git configuration.

 doc/contributing.texi                     | 102 +++++-------
 doc/guix.texi                             |   2 +-
 etc/git/gitconfig                         |  15 ++
 etc/teams.scm.in                          |  39 ++++-
 gnu/local.mk                              |   1 +
 gnu/packages/patches/git-header-cmd.patch | 180 ++++++++++++++++++++++
 gnu/packages/version-control.scm          |   3 +-
 7 files changed, 267 insertions(+), 75 deletions(-)
 create mode 100644 gnu/packages/patches/git-header-cmd.patch


base-commit: 5b545763ed9b8a3fade7f756d543819fc090953f
-- 
2.39.2

bug#58813: [PATCH 1/5] gnu: git: Apply patch adding the --header-cmd feature.

[Maxim Cournoyer]

In preparation to fix <https://issues.guix.gnu.org/58813>.

* gnu/packages/patches/git-header-cmd.patch: New file.
* gnu/local.mk (dist_patch_DATA): Register it.
* gnu/packages/version-control.scm (git) [source]: Apply patch.
---
 gnu/local.mk                              |   1 +
 gnu/packages/patches/git-header-cmd.patch | 180 ++++++++++++++++++++++
 gnu/packages/version-control.scm          |   3 +-
 3 files changed, 183 insertions(+), 1 deletion(-)
 create mode 100644 gnu/packages/patches/git-header-cmd.patch

diff --git a/gnu/local.mk b/gnu/local.mk
index b631fa6d5a..d7c7ca48e7 100644
--- a/gnu/local.mk
+++ b/gnu/local.mk
@@ -1209,6 +1209,7 @@ dist_patch_DATA =						\
   %D%/packages/patches/gemmi-fix-sajson-types.patch		\
   %D%/packages/patches/genimage-mke2fs-test.patch		\
   %D%/packages/patches/geoclue-config.patch			\
+  %D%/packages/patches/git-header-cmd.patch			\
   %D%/packages/patches/ghc-8.0-fall-back-to-madv_dontneed.patch	\
   %D%/packages/patches/ghc-9.2-glibc-2.33-link-order.patch \
   %D%/packages/patches/ghc-testsuite-dlopen-pie.patch		\
diff --git a/gnu/packages/patches/git-header-cmd.patch b/gnu/packages/patches/git-header-cmd.patch
new file mode 100644
index 0000000000..fdd34fe4a4
--- /dev/null
+++ b/gnu/packages/patches/git-header-cmd.patch
@@ -0,0 +1,180 @@
+Add a '--header-cmd' to git send-email.
+
+Upstream status can be tracked at:
+https://lore.kernel.org/git/20230423122744.4865-1-maxim.cournoyer@gmail.com/T/#t
+
+diff --git a/Documentation/config/sendemail.txt b/Documentation/config/sendemail.txt
+index 51da7088a8..3d0f516520 100644
+--- a/Documentation/config/sendemail.txt
++++ b/Documentation/config/sendemail.txt
+@@ -58,6 +58,7 @@ sendemail.annotate::
+ sendemail.bcc::
+ sendemail.cc::
+ sendemail.ccCmd::
++sendemail.headerCmd::
+ sendemail.chainReplyTo::
+ sendemail.envelopeSender::
+ sendemail.from::
+diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
+index b0f438ec99..354c0d06db 100644
+--- a/Documentation/git-send-email.txt
++++ b/Documentation/git-send-email.txt
+@@ -320,6 +320,11 @@ Automating
+ 	Output of this command must be single email address per line.
+ 	Default is the value of `sendemail.ccCmd` configuration value.
+ 
++--header-cmd=<command>::
++	Specify a command to execute once per patch file which should
++	generate arbitrary, patch file specific header entries.
++	Default is the value of `sendemail.headerCmd` configuration value.
++
+ --[no-]chain-reply-to::
+ 	If this is set, each email will be sent as a reply to the previous
+ 	email sent.  If disabled with "--no-chain-reply-to", all emails after
+diff --git a/git-send-email.perl b/git-send-email.perl
+index fd8cd0d46f..676dd83d89 100755
+--- a/git-send-email.perl
++++ b/git-send-email.perl
+@@ -2,6 +2,7 @@
+ #
+ # Copyright 2002,2005 Greg Kroah-Hartman <greg@kroah.com>
+ # Copyright 2005 Ryan Anderson <ryan@michonline.com>
++# Copyright 2023 Maxim Cournoyer <maxim.cournoyer@gmail.com>
+ #
+ # GPL v2 (See COPYING)
+ #
+@@ -87,8 +88,9 @@ sub usage {
+ 
+   Automating:
+     --identity              <str>  * Use the sendemail.<id> options.
+-    --to-cmd                <str>  * Email To: via `<str> \$patch_path`
+-    --cc-cmd                <str>  * Email Cc: via `<str> \$patch_path`
++    --to-cmd                <str>  * Email To: via `<str> \$patch_path`.
++    --cc-cmd                <str>  * Email Cc: via `<str> \$patch_path`.
++    --header-cmd            <str>  * Add headers via `<str> \$patch_path`.
+     --suppress-cc           <str>  * author, self, sob, cc, cccmd, body, bodycc, misc-by, all.
+     --[no-]cc-cover                * Email Cc: addresses in the cover letter.
+     --[no-]to-cover                * Email To: addresses in the cover letter.
+@@ -269,7 +271,7 @@ sub do_edit {
+ # Variables with corresponding config settings
+ my ($suppress_from, $signed_off_by_cc);
+ my ($cover_cc, $cover_to);
+-my ($to_cmd, $cc_cmd);
++my ($to_cmd, $cc_cmd, $header_cmd);
+ my ($smtp_server, $smtp_server_port, @smtp_server_options);
+ my ($smtp_authuser, $smtp_encryption, $smtp_ssl_cert_path);
+ my ($batch_size, $relogin_delay);
+@@ -318,6 +320,7 @@ sub do_edit {
+     "tocmd" => \$to_cmd,
+     "cc" => \@config_cc,
+     "cccmd" => \$cc_cmd,
++    "headercmd" => \$header_cmd,
+     "aliasfiletype" => \$aliasfiletype,
+     "bcc" => \@config_bcc,
+     "suppresscc" => \@suppress_cc,
+@@ -519,6 +522,7 @@ sub config_regexp {
+ 		    "compose" => \$compose,
+ 		    "quiet" => \$quiet,
+ 		    "cc-cmd=s" => \$cc_cmd,
++		    "header-cmd=s" => \$header_cmd,
+ 		    "suppress-from!" => \$suppress_from,
+ 		    "no-suppress-from" => sub {$suppress_from = 0},
+ 		    "suppress-cc=s" => \@suppress_cc,
+@@ -1776,6 +1780,9 @@ sub process_file {
+ 			push(@header, $_);
+ 		}
+ 	}
++	# Add computed headers, if applicable.
++	push @header, execute_cmd("header-cmd", $header_cmd, $t)
++		if defined $header_cmd;
+ 	# Now parse the header
+ 	foreach(@header) {
+ 		if (/^From /) {
+@@ -2006,15 +2013,30 @@ sub process_file {
+ 	}
+ }
+ 
++# Execute a command (e.g., $x_cmd) and return its output lines as an
++# array.
++sub execute_cmd {
++	my ($prefix, $cmd, $file) = @_;
++	my @lines = ();
++	open my $fh, "-|", "$cmd \Q$file\E"
++		or die sprintf(__("(%s) Could not execute '%s'"), $prefix, $cmd);
++	while (my $line = <$fh>) {
++		last if $line =~ /^$/;
++		push @lines, $line;
++	}
++	close $fh
++	    or die sprintf(__("(%s) failed to close pipe to '%s'"), $prefix, $cmd);
++	return @lines;
++}
++
+ # Execute a command (e.g. $to_cmd) to get a list of email addresses
+ # and return a results array
+ sub recipients_cmd {
+ 	my ($prefix, $what, $cmd, $file) = @_;
+-
++	my @lines = ();
+ 	my @addresses = ();
+-	open my $fh, "-|", "$cmd \Q$file\E"
+-	    or die sprintf(__("(%s) Could not execute '%s'"), $prefix, $cmd);
+-	while (my $address = <$fh>) {
++	@lines = execute_cmd($prefix, $cmd, $file);
++	for my $address (@lines) {
+ 		$address =~ s/^\s*//g;
+ 		$address =~ s/\s*$//g;
+ 		$address = sanitize_address($address);
+@@ -2023,8 +2045,6 @@ sub recipients_cmd {
+ 		printf(__("(%s) Adding %s: %s from: '%s'\n"),
+ 		       $prefix, $what, $address, $cmd) unless $quiet;
+ 		}
+-	close $fh
+-	    or die sprintf(__("(%s) failed to close pipe to '%s'"), $prefix, $cmd);
+ 	return @addresses;
+ }
+ 
+diff --git a/t/t9001-send-email.sh b/t/t9001-send-email.sh
+index 0de83b5d2b..3393725107 100755
+--- a/t/t9001-send-email.sh
++++ b/t/t9001-send-email.sh
+@@ -374,13 +374,16 @@ test_expect_success $PREREQ,!AUTOIDENT 'broken implicit ident aborts send-email'
+ 	)
+ '
+ 
+-test_expect_success $PREREQ 'setup tocmd and cccmd scripts' '
++test_expect_success $PREREQ 'setup cmd scripts' '
+ 	write_script tocmd-sed <<-\EOF &&
+ 	sed -n -e "s/^tocmd--//p" "$1"
+ 	EOF
+-	write_script cccmd-sed <<-\EOF
++	write_script cccmd-sed <<-\EOF &&
+ 	sed -n -e "s/^cccmd--//p" "$1"
+ 	EOF
++	write_script headercmd-sed <<-\EOF
++	sed -n -e "s/^headercmd--//p" "$1"
++	EOF
+ '
+ 
+ test_expect_success $PREREQ 'tocmd works' '
+@@ -410,6 +413,20 @@ test_expect_success $PREREQ 'cccmd works' '
+ 	grep "^	cccmd@example.com" msgtxt1
+ '
+ 
++test_expect_success $PREREQ 'headercmd works' '
++	clean_fake_sendmail &&
++	cp $patches headercmd.patch &&
++	echo "headercmd--X-Debbugs-CC: dummy@example.com" >>headercmd.patch &&
++	git send-email \
++		--from="Example <nobody@example.com>" \
++		--to=nobody@example.com \
++		--header-cmd=./headercmd-sed \
++		--smtp-server="$(pwd)/fake.sendmail" \
++		headercmd.patch \
++		&&
++	grep "^X-Debbugs-CC: dummy@example.com" msgtxt1
++'
++
+ test_expect_success $PREREQ 'reject long lines' '
+ 	z8=zzzzzzzz &&
+ 	z64=$z8$z8$z8$z8$z8$z8$z8$z8 &&
diff --git a/gnu/packages/version-control.scm b/gnu/packages/version-control.scm
index 302f7c90ad..d5d88b99ed 100644
--- a/gnu/packages/version-control.scm
+++ b/gnu/packages/version-control.scm
@@ -232,7 +232,8 @@ (define-public git
                                 version ".tar.xz"))
             (sha256
              (base32
-              "1mpjvhyw8mv2q941xny4d0gw3mb6b4bqaqbh73jd8b1v6zqpaps7"))))
+              "1mpjvhyw8mv2q941xny4d0gw3mb6b4bqaqbh73jd8b1v6zqpaps7"))
+            (patches (search-patches "git-header-cmd.patch"))))
    (build-system gnu-build-system)
    (native-inputs
     `(("native-perl" ,perl)
-- 
2.39.2

bug#58813: [PATCH 1/5] gnu: git: Apply patch adding the --header-cmd feature.

[Liliana Marie Prikler]

Am Sonntag, dem 23.04.2023 um 12:04 -0400 schrieb Maxim Cournoyer:
> In preparation to fix <https://issues.guix.gnu.org/58813>.
> 
> * gnu/packages/patches/git-header-cmd.patch: New file.
> * gnu/local.mk (dist_patch_DATA): Register it.
> * gnu/packages/version-control.scm (git) [source]: Apply patch.
> ---
Don't forget to also send this patch to git proper.  I'm sure that
other distros will have a use for it.

Cheers

bug#58813: [PATCH 1/5] gnu: git: Apply patch adding the --header-cmd feature.

[Maxim Cournoyer]

Hi Liliana,

Liliana Marie Prikler <liliana.prikler@gmail.com> writes:

> Am Sonntag, dem 23.04.2023 um 12:04 -0400 schrieb Maxim Cournoyer:
>> In preparation to fix <https://issues.guix.gnu.org/58813>.
>> 
>> * gnu/packages/patches/git-header-cmd.patch: New file.
>> * gnu/local.mk (dist_patch_DATA): Register it.
>> * gnu/packages/version-control.scm (git) [source]: Apply patch.
>> ---
> Don't forget to also send this patch to git proper.  I'm sure that
> other distros will have a use for it.

Already the case (see the top comment in the patch itself) :-).

-- 
Thanks,
Maxim

bug#58813: [PATCH 2/5] teams: Add 'cc-members-header-cmd' action.

[Maxim Cournoyer]

* etc/teams.scm.in (patch->teams): New procedure.
(main): Use it.  Add a new "cc-members-header-cmd" command; document it.
---
 etc/teams.scm.in | 20 +++++++++++++++-----
 1 file changed, 15 insertions(+), 5 deletions(-)

diff --git a/etc/teams.scm.in b/etc/teams.scm.in
index 37a3c8e191..408db8b7d5 100644
--- a/etc/teams.scm.in
+++ b/etc/teams.scm.in
@@ -5,7 +5,7 @@
 ;;; GNU Guix --- Functional package management for GNU
 ;;; Copyright © 2022, 2023 Ricardo Wurmus <rekado@elephly.net>
 ;;; Copyright © 2022 Mathieu Othacehe <othacehe@gnu.org>
-;;; Copyright © 2022 Maxim Cournoyer <maxim.cournoyer@gmail.com>
+;;; Copyright © 2022, 2023 Maxim Cournoyer <maxim.cournoyer@gmail.com>
 ;;;
 ;;; This file is part of GNU Guix.
 ;;;
@@ -696,6 +696,12 @@ (define (git-patch->revisions file)
          (rev-start (string-append rev-end "^")))
     (list rev-start rev-end)))
 
+(define (patch->teams patch-file)
+  "Return the name of the teams in scope for the changes in PATCH-FILE."
+  (map (compose symbol->string team-id)
+       (find-team-by-scope (apply diff-revisions
+                                  (git-patch->revisions patch-file)))))
+
 \f
 (define (main . args)
   (match args
@@ -708,11 +714,13 @@ (define (main . args)
     (("cc-members" rev-start rev-end)
      (apply cc (find-team-by-scope
                 (diff-revisions rev-start rev-end))))
+    (("cc-members-header-cmd" patch-file)
+     (for-each (lambda (team-name)
+                 (list-members (find-team team-name) (current-output-port)
+                               "X-Debbugs-Cc: "))
+               (patch->teams patch-file)))
     (("get-maintainer" patch-file)
-     (apply main "list-members"
-            (map (compose symbol->string team-id)
-                 (find-team-by-scope (apply diff-revisions
-                                            (git-patch->revisions patch-file))))))
+     (apply main "list-members" (patch->teams patch-file)))
     (("list-teams" . args)
      (list-teams))
     (("list-members" . team-names)
@@ -729,6 +737,8 @@ (define (main . args)
       get git send-email flags for cc-ing <team-name>
   cc-members <start> <end> | patch
       cc teams related to files changed between revisions or in a patch file
+  cc-members-header-cmd <patch>
+      cc-members variant for use with 'git send-email --header-cmd'
   list-teams
       list teams and their members
   list-members <team-name>
-- 
2.39.2

bug#58813: [PATCH 3/5] teams: Add a configure-git action.

[Maxim Cournoyer]

* etc/git/gitconfig: Augment configuration template with useful options to
allow for auto-configuration.
* etc/teams.scm.in (configure-git): New procedure.
(main): Register it and add documentation.
---
 etc/git/gitconfig | 15 +++++++++++++++
 etc/teams.scm.in  | 12 +++++++++++-
 2 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/etc/git/gitconfig b/etc/git/gitconfig
index c9ebdc8fa8..0b6984a05f 100644
--- a/etc/git/gitconfig
+++ b/etc/git/gitconfig
@@ -1,5 +1,20 @@
+[commit]
+        gpgsign = true
+
 [diff "scheme"]
 	xfuncname = "^(\\(define.*)$"
 
 [diff "texinfo"]
 	xfuncname = "^@node[[:space:]]+([^,]+).*$"
+
+[format]
+        useAutoBase = true
+        thread = shallow
+
+[pull]
+        rebase = true
+
+[sendemail]
+        to = guix-patches@gnu.org
+        headerCmd = etc/teams.scm cc-members-header-cmd
+        thread = no
diff --git a/etc/teams.scm.in b/etc/teams.scm.in
index 408db8b7d5..8203446446 100644
--- a/etc/teams.scm.in
+++ b/etc/teams.scm.in
@@ -36,8 +36,9 @@
              (ice-9 regex)
              (ice-9 match)
              (ice-9 rdelim)
+             (git)
              (guix ui)
-             (git))
+             (guix build utils))
 
 (define-record-type <team>
   (make-team id name description members scope)
@@ -702,6 +703,11 @@ (define (patch->teams patch-file)
        (find-team-by-scope (apply diff-revisions
                                   (git-patch->revisions patch-file)))))
 
+(define (configure-git)
+  "Automate the required Git configurations for the Guix project."
+  (invoke "git" "config" "include.path" "../etc/git/gitconfig")
+  (copy-file "etc/git/pre-push" ".git/hooks/pre-push"))
+
 \f
 (define (main . args)
   (match args
@@ -719,6 +725,8 @@ (define (main . args)
                  (list-members (find-team team-name) (current-output-port)
                                "X-Debbugs-Cc: "))
                (patch->teams patch-file)))
+    (("configure-git")
+     (configure-git))
     (("get-maintainer" patch-file)
      (apply main "list-members" (patch->teams patch-file)))
     (("list-teams" . args)
@@ -739,6 +747,8 @@ (define (main . args)
       cc teams related to files changed between revisions or in a patch file
   cc-members-header-cmd <patch>
       cc-members variant for use with 'git send-email --header-cmd'
+  configure-git
+      automatically configure your Git checkout for Guix
   list-teams
       list teams and their members
   list-members <team-name>
-- 
2.39.2

bug#58813: [PATCH 3/5] teams: Add a configure-git action.

[Liliana Marie Prikler]

Am Sonntag, dem 23.04.2023 um 12:04 -0400 schrieb Maxim Cournoyer:
> * etc/git/gitconfig: Augment configuration template with useful
> options to
> allow for auto-configuration.
> * etc/teams.scm.in (configure-git): New procedure.
> (main): Register it and add documentation.
I think configure-git is somewhat out of scope inside teams.scm.  We do
already tell people to set up their push hooks, so we probably ought to
solve this via documentation (or a separate dedicated script) as well.

Otherwise LGTM.

Cheers

bug#58813: [PATCH 3/5] teams: Add a configure-git action.

[Maxim Cournoyer]

Hi Liliana,

Liliana Marie Prikler <liliana.prikler@gmail.com> writes:

> Am Sonntag, dem 23.04.2023 um 12:04 -0400 schrieb Maxim Cournoyer:
>> * etc/git/gitconfig: Augment configuration template with useful
>> options to
>> allow for auto-configuration.
>> * etc/teams.scm.in (configure-git): New procedure.
>> (main): Register it and add documentation.
> I think configure-git is somewhat out of scope inside teams.scm.  We do
> already tell people to set up their push hooks, so we probably ought to
> solve this via documentation (or a separate dedicated script) as well.

You're right that it feels a bit out of place.  The other idea I had was
to add it as a Makefile target.  This one would have the benefit of
being smart about when to re-run the command (if the gitconfig or
pre-push files changed).

Would that fit better?

> Otherwise LGTM.

OK!  Thanks for weighing in.

-- 
Thanks,
Maxim

bug#58813: [PATCH v2 0/5] Fix teams.scm by use of a new --header-cmd git send-email option.

[Maxim Cournoyer]

This v2 moves the Git autoconfiguration from teams.scm to to the build
system (Automake).  This has the benefit of happening on every build
when necessary, further automating things and avoiding the need to
remember to refresh the pre-push hooks at times.  The rest is mostly
unchanged except for light adjustments to the doc commit.

Thanks!

Maxim Cournoyer (5):
  gnu: git: Apply patch adding the --header-cmd feature.
  teams: Add 'cc-members-header-cmd' action.
  Makefile.am: Auto-configure Git on 'make'.
  teams: Add a 'cc-mentors-header-cmd' action.
  doc: Simplify contributing section by automating git configuration.

 Makefile.am                               |  10 ++
 doc/contributing.texi                     | 104 +++++--------
 doc/guix.texi                             |   2 +-
 etc/git/gitconfig                         |  15 ++
 etc/teams.scm.in                          |  27 +++-
 gnu/local.mk                              |   1 +
 gnu/packages/patches/git-header-cmd.patch | 180 ++++++++++++++++++++++
 gnu/packages/version-control.scm          |   3 +-
 8 files changed, 265 insertions(+), 77 deletions(-)
 create mode 100644 gnu/packages/patches/git-header-cmd.patch


base-commit: 5b545763ed9b8a3fade7f756d543819fc090953f
-- 
2.39.2

bug#58813: [PATCH v2 1/5] gnu: git: Apply patch adding the --header-cmd feature.

[Maxim Cournoyer]

In preparation to fix <https://issues.guix.gnu.org/58813>.

* gnu/packages/patches/git-header-cmd.patch: New file.
* gnu/local.mk (dist_patch_DATA): Register it.
* gnu/packages/version-control.scm (git) [source]: Apply patch.
---
 gnu/local.mk                              |   1 +
 gnu/packages/patches/git-header-cmd.patch | 180 ++++++++++++++++++++++
 gnu/packages/version-control.scm          |   3 +-
 3 files changed, 183 insertions(+), 1 deletion(-)
 create mode 100644 gnu/packages/patches/git-header-cmd.patch

diff --git a/gnu/local.mk b/gnu/local.mk
index b631fa6d5a..d7c7ca48e7 100644
--- a/gnu/local.mk
+++ b/gnu/local.mk
@@ -1209,6 +1209,7 @@ dist_patch_DATA =						\
   %D%/packages/patches/gemmi-fix-sajson-types.patch		\
   %D%/packages/patches/genimage-mke2fs-test.patch		\
   %D%/packages/patches/geoclue-config.patch			\
+  %D%/packages/patches/git-header-cmd.patch			\
   %D%/packages/patches/ghc-8.0-fall-back-to-madv_dontneed.patch	\
   %D%/packages/patches/ghc-9.2-glibc-2.33-link-order.patch \
   %D%/packages/patches/ghc-testsuite-dlopen-pie.patch		\
diff --git a/gnu/packages/patches/git-header-cmd.patch b/gnu/packages/patches/git-header-cmd.patch
new file mode 100644
index 0000000000..fdd34fe4a4
--- /dev/null
+++ b/gnu/packages/patches/git-header-cmd.patch
@@ -0,0 +1,180 @@
+Add a '--header-cmd' to git send-email.
+
+Upstream status can be tracked at:
+https://lore.kernel.org/git/20230423122744.4865-1-maxim.cournoyer@gmail.com/T/#t
+
+diff --git a/Documentation/config/sendemail.txt b/Documentation/config/sendemail.txt
+index 51da7088a8..3d0f516520 100644
+--- a/Documentation/config/sendemail.txt
++++ b/Documentation/config/sendemail.txt
+@@ -58,6 +58,7 @@ sendemail.annotate::
+ sendemail.bcc::
+ sendemail.cc::
+ sendemail.ccCmd::
++sendemail.headerCmd::
+ sendemail.chainReplyTo::
+ sendemail.envelopeSender::
+ sendemail.from::
+diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
+index b0f438ec99..354c0d06db 100644
+--- a/Documentation/git-send-email.txt
++++ b/Documentation/git-send-email.txt
+@@ -320,6 +320,11 @@ Automating
+ 	Output of this command must be single email address per line.
+ 	Default is the value of `sendemail.ccCmd` configuration value.
+ 
++--header-cmd=<command>::
++	Specify a command to execute once per patch file which should
++	generate arbitrary, patch file specific header entries.
++	Default is the value of `sendemail.headerCmd` configuration value.
++
+ --[no-]chain-reply-to::
+ 	If this is set, each email will be sent as a reply to the previous
+ 	email sent.  If disabled with "--no-chain-reply-to", all emails after
+diff --git a/git-send-email.perl b/git-send-email.perl
+index fd8cd0d46f..676dd83d89 100755
+--- a/git-send-email.perl
++++ b/git-send-email.perl
+@@ -2,6 +2,7 @@
+ #
+ # Copyright 2002,2005 Greg Kroah-Hartman <greg@kroah.com>
+ # Copyright 2005 Ryan Anderson <ryan@michonline.com>
++# Copyright 2023 Maxim Cournoyer <maxim.cournoyer@gmail.com>
+ #
+ # GPL v2 (See COPYING)
+ #
+@@ -87,8 +88,9 @@ sub usage {
+ 
+   Automating:
+     --identity              <str>  * Use the sendemail.<id> options.
+-    --to-cmd                <str>  * Email To: via `<str> \$patch_path`
+-    --cc-cmd                <str>  * Email Cc: via `<str> \$patch_path`
++    --to-cmd                <str>  * Email To: via `<str> \$patch_path`.
++    --cc-cmd                <str>  * Email Cc: via `<str> \$patch_path`.
++    --header-cmd            <str>  * Add headers via `<str> \$patch_path`.
+     --suppress-cc           <str>  * author, self, sob, cc, cccmd, body, bodycc, misc-by, all.
+     --[no-]cc-cover                * Email Cc: addresses in the cover letter.
+     --[no-]to-cover                * Email To: addresses in the cover letter.
+@@ -269,7 +271,7 @@ sub do_edit {
+ # Variables with corresponding config settings
+ my ($suppress_from, $signed_off_by_cc);
+ my ($cover_cc, $cover_to);
+-my ($to_cmd, $cc_cmd);
++my ($to_cmd, $cc_cmd, $header_cmd);
+ my ($smtp_server, $smtp_server_port, @smtp_server_options);
+ my ($smtp_authuser, $smtp_encryption, $smtp_ssl_cert_path);
+ my ($batch_size, $relogin_delay);
+@@ -318,6 +320,7 @@ sub do_edit {
+     "tocmd" => \$to_cmd,
+     "cc" => \@config_cc,
+     "cccmd" => \$cc_cmd,
++    "headercmd" => \$header_cmd,
+     "aliasfiletype" => \$aliasfiletype,
+     "bcc" => \@config_bcc,
+     "suppresscc" => \@suppress_cc,
+@@ -519,6 +522,7 @@ sub config_regexp {
+ 		    "compose" => \$compose,
+ 		    "quiet" => \$quiet,
+ 		    "cc-cmd=s" => \$cc_cmd,
++		    "header-cmd=s" => \$header_cmd,
+ 		    "suppress-from!" => \$suppress_from,
+ 		    "no-suppress-from" => sub {$suppress_from = 0},
+ 		    "suppress-cc=s" => \@suppress_cc,
+@@ -1776,6 +1780,9 @@ sub process_file {
+ 			push(@header, $_);
+ 		}
+ 	}
++	# Add computed headers, if applicable.
++	push @header, execute_cmd("header-cmd", $header_cmd, $t)
++		if defined $header_cmd;
+ 	# Now parse the header
+ 	foreach(@header) {
+ 		if (/^From /) {
+@@ -2006,15 +2013,30 @@ sub process_file {
+ 	}
+ }
+ 
++# Execute a command (e.g., $x_cmd) and return its output lines as an
++# array.
++sub execute_cmd {
++	my ($prefix, $cmd, $file) = @_;
++	my @lines = ();
++	open my $fh, "-|", "$cmd \Q$file\E"
++		or die sprintf(__("(%s) Could not execute '%s'"), $prefix, $cmd);
++	while (my $line = <$fh>) {
++		last if $line =~ /^$/;
++		push @lines, $line;
++	}
++	close $fh
++	    or die sprintf(__("(%s) failed to close pipe to '%s'"), $prefix, $cmd);
++	return @lines;
++}
++
+ # Execute a command (e.g. $to_cmd) to get a list of email addresses
+ # and return a results array
+ sub recipients_cmd {
+ 	my ($prefix, $what, $cmd, $file) = @_;
+-
++	my @lines = ();
+ 	my @addresses = ();
+-	open my $fh, "-|", "$cmd \Q$file\E"
+-	    or die sprintf(__("(%s) Could not execute '%s'"), $prefix, $cmd);
+-	while (my $address = <$fh>) {
++	@lines = execute_cmd($prefix, $cmd, $file);
++	for my $address (@lines) {
+ 		$address =~ s/^\s*//g;
+ 		$address =~ s/\s*$//g;
+ 		$address = sanitize_address($address);
+@@ -2023,8 +2045,6 @@ sub recipients_cmd {
+ 		printf(__("(%s) Adding %s: %s from: '%s'\n"),
+ 		       $prefix, $what, $address, $cmd) unless $quiet;
+ 		}
+-	close $fh
+-	    or die sprintf(__("(%s) failed to close pipe to '%s'"), $prefix, $cmd);
+ 	return @addresses;
+ }
+ 
+diff --git a/t/t9001-send-email.sh b/t/t9001-send-email.sh
+index 0de83b5d2b..3393725107 100755
+--- a/t/t9001-send-email.sh
++++ b/t/t9001-send-email.sh
+@@ -374,13 +374,16 @@ test_expect_success $PREREQ,!AUTOIDENT 'broken implicit ident aborts send-email'
+ 	)
+ '
+ 
+-test_expect_success $PREREQ 'setup tocmd and cccmd scripts' '
++test_expect_success $PREREQ 'setup cmd scripts' '
+ 	write_script tocmd-sed <<-\EOF &&
+ 	sed -n -e "s/^tocmd--//p" "$1"
+ 	EOF
+-	write_script cccmd-sed <<-\EOF
++	write_script cccmd-sed <<-\EOF &&
+ 	sed -n -e "s/^cccmd--//p" "$1"
+ 	EOF
++	write_script headercmd-sed <<-\EOF
++	sed -n -e "s/^headercmd--//p" "$1"
++	EOF
+ '
+ 
+ test_expect_success $PREREQ 'tocmd works' '
+@@ -410,6 +413,20 @@ test_expect_success $PREREQ 'cccmd works' '
+ 	grep "^	cccmd@example.com" msgtxt1
+ '
+ 
++test_expect_success $PREREQ 'headercmd works' '
++	clean_fake_sendmail &&
++	cp $patches headercmd.patch &&
++	echo "headercmd--X-Debbugs-CC: dummy@example.com" >>headercmd.patch &&
++	git send-email \
++		--from="Example <nobody@example.com>" \
++		--to=nobody@example.com \
++		--header-cmd=./headercmd-sed \
++		--smtp-server="$(pwd)/fake.sendmail" \
++		headercmd.patch \
++		&&
++	grep "^X-Debbugs-CC: dummy@example.com" msgtxt1
++'
++
+ test_expect_success $PREREQ 'reject long lines' '
+ 	z8=zzzzzzzz &&
+ 	z64=$z8$z8$z8$z8$z8$z8$z8$z8 &&
diff --git a/gnu/packages/version-control.scm b/gnu/packages/version-control.scm
index 302f7c90ad..d5d88b99ed 100644
--- a/gnu/packages/version-control.scm
+++ b/gnu/packages/version-control.scm
@@ -232,7 +232,8 @@ (define-public git
                                 version ".tar.xz"))
             (sha256
              (base32
-              "1mpjvhyw8mv2q941xny4d0gw3mb6b4bqaqbh73jd8b1v6zqpaps7"))))
+              "1mpjvhyw8mv2q941xny4d0gw3mb6b4bqaqbh73jd8b1v6zqpaps7"))
+            (patches (search-patches "git-header-cmd.patch"))))
    (build-system gnu-build-system)
    (native-inputs
     `(("native-perl" ,perl)
-- 
2.39.2

bug#58813: [PATCH v2 2/5] teams: Add 'cc-members-header-cmd' action.

[Maxim Cournoyer]

* etc/teams.scm.in (patch->teams): New procedure.
(main): Use it.  Add a new "cc-members-header-cmd" command; document it.
---
 etc/teams.scm.in | 20 +++++++++++++++-----
 1 file changed, 15 insertions(+), 5 deletions(-)

diff --git a/etc/teams.scm.in b/etc/teams.scm.in
index 37a3c8e191..408db8b7d5 100644
--- a/etc/teams.scm.in
+++ b/etc/teams.scm.in
@@ -5,7 +5,7 @@
 ;;; GNU Guix --- Functional package management for GNU
 ;;; Copyright © 2022, 2023 Ricardo Wurmus <rekado@elephly.net>
 ;;; Copyright © 2022 Mathieu Othacehe <othacehe@gnu.org>
-;;; Copyright © 2022 Maxim Cournoyer <maxim.cournoyer@gmail.com>
+;;; Copyright © 2022, 2023 Maxim Cournoyer <maxim.cournoyer@gmail.com>
 ;;;
 ;;; This file is part of GNU Guix.
 ;;;
@@ -696,6 +696,12 @@ (define (git-patch->revisions file)
          (rev-start (string-append rev-end "^")))
     (list rev-start rev-end)))
 
+(define (patch->teams patch-file)
+  "Return the name of the teams in scope for the changes in PATCH-FILE."
+  (map (compose symbol->string team-id)
+       (find-team-by-scope (apply diff-revisions
+                                  (git-patch->revisions patch-file)))))
+
 \f
 (define (main . args)
   (match args
@@ -708,11 +714,13 @@ (define (main . args)
     (("cc-members" rev-start rev-end)
      (apply cc (find-team-by-scope
                 (diff-revisions rev-start rev-end))))
+    (("cc-members-header-cmd" patch-file)
+     (for-each (lambda (team-name)
+                 (list-members (find-team team-name) (current-output-port)
+                               "X-Debbugs-Cc: "))
+               (patch->teams patch-file)))
     (("get-maintainer" patch-file)
-     (apply main "list-members"
-            (map (compose symbol->string team-id)
-                 (find-team-by-scope (apply diff-revisions
-                                            (git-patch->revisions patch-file))))))
+     (apply main "list-members" (patch->teams patch-file)))
     (("list-teams" . args)
      (list-teams))
     (("list-members" . team-names)
@@ -729,6 +737,8 @@ (define (main . args)
       get git send-email flags for cc-ing <team-name>
   cc-members <start> <end> | patch
       cc teams related to files changed between revisions or in a patch file
+  cc-members-header-cmd <patch>
+      cc-members variant for use with 'git send-email --header-cmd'
   list-teams
       list teams and their members
   list-members <team-name>
-- 
2.39.2

bug#58813: [PATCH v2 3/5] Makefile.am: Auto-configure Git on 'make'.

[Maxim Cournoyer]

This means we do not need to worry anymore about manually syncing the pre-push
git hook or the Guix-provided git configuration.

* etc/git/gitconfig: Augment configuration template with useful options to
allow for auto-configuration.
* Makefile.am (.git/hooks/pre-push, .git/config): New targets.
(nodist_noinst_DATA): New primary variable holding the above targets.
---
 Makefile.am       | 10 ++++++++++
 etc/git/gitconfig | 15 +++++++++++++++
 2 files changed, 25 insertions(+)

diff --git a/Makefile.am b/Makefile.am
index 23b939b674..7daa7d66f7 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -14,6 +14,7 @@
 # Copyright © 2018 Oleg Pykhalov <go.wigust@gmail.com>
 # Copyright © 2018 Alex Vong <alexvong1995@gmail.com>
 # Copyright © 2019 Efraim Flashner <efraim@flashner.co.il>
+# Copyright © 2020, 2021, 2023 Maxim Cournoyer <maxim.cournoyer@gmail.com>
 # Copyright © 2021 Chris Marusich <cmmarusich@gmail.com>
 # Copyright © 2021 Andrew Tropin <andrew@trop.in>
 #
@@ -1109,6 +1110,15 @@ cuirass-jobs: $(GOBJECTS)
 .PHONY: clean-go make-go as-derivation authenticate
 .PHONY: update-guix-package update-NEWS cuirass-jobs release
 
+# Git auto-configuration.
+.git/hooks/pre-push: etc/git/pre-push
+	cp etc/git/pre-push .git/hooks/pre-push
+
+.git/config: etc/git/gitconfig
+	git config include.path ../etc/git/gitconfig
+
+nodist_noinst_DATA = .git/hooks/pre-push .git/config
+
 # Downloading up-to-date PO files.
 
 WEBLATE_REPO = https://framagit.org/tyreunom/guix-translations
diff --git a/etc/git/gitconfig b/etc/git/gitconfig
index c9ebdc8fa8..0b6984a05f 100644
--- a/etc/git/gitconfig
+++ b/etc/git/gitconfig
@@ -1,5 +1,20 @@
+[commit]
+        gpgsign = true
+
 [diff "scheme"]
 	xfuncname = "^(\\(define.*)$"
 
 [diff "texinfo"]
 	xfuncname = "^@node[[:space:]]+([^,]+).*$"
+
+[format]
+        useAutoBase = true
+        thread = shallow
+
+[pull]
+        rebase = true
+
+[sendemail]
+        to = guix-patches@gnu.org
+        headerCmd = etc/teams.scm cc-members-header-cmd
+        thread = no
-- 
2.39.2

bug#58813: [PATCH v2 3/5] Makefile.am: Auto-configure Git on 'make'.

[Liliana Marie Prikler]

Am Sonntag, dem 23.04.2023 um 22:29 -0400 schrieb Maxim Cournoyer:
> This means we do not need to worry anymore about manually syncing the
> pre-push git hook or the Guix-provided git configuration.
IIUC we still need to invoke 'make .git/whatever' manually, and I'd
actually like it to be that way, just with a nice phony target like
'make git-config' or 'make .git'.  WDYT?

> * etc/git/gitconfig: Augment configuration template with useful
> options to allow for auto-configuration.
> * Makefile.am (.git/hooks/pre-push, .git/config): New targets.
> (nodist_noinst_DATA): New primary variable holding the above targets.
> ---
>  Makefile.am       | 10 ++++++++++
>  etc/git/gitconfig | 15 +++++++++++++++
>  2 files changed, 25 insertions(+)
> 
> diff --git a/Makefile.am b/Makefile.am
> index 23b939b674..7daa7d66f7 100644
> --- a/Makefile.am
> +++ b/Makefile.am
> @@ -14,6 +14,7 @@
>  # Copyright © 2018 Oleg Pykhalov <go.wigust@gmail.com>
>  # Copyright © 2018 Alex Vong <alexvong1995@gmail.com>
>  # Copyright © 2019 Efraim Flashner <efraim@flashner.co.il>
> +# Copyright © 2020, 2021, 2023 Maxim Cournoyer
> <maxim.cournoyer@gmail.com>
>  # Copyright © 2021 Chris Marusich <cmmarusich@gmail.com>
>  # Copyright © 2021 Andrew Tropin <andrew@trop.in>
>  #
> @@ -1109,6 +1110,15 @@ cuirass-jobs: $(GOBJECTS)
>  .PHONY: clean-go make-go as-derivation authenticate
>  .PHONY: update-guix-package update-NEWS cuirass-jobs release
>  
> +# Git auto-configuration.
> +.git/hooks/pre-push: etc/git/pre-push
> +       cp etc/git/pre-push .git/hooks/pre-push
> +
> +.git/config: etc/git/gitconfig
> +       git config include.path ../etc/git/gitconfig
> +
> +nodist_noinst_DATA = .git/hooks/pre-push .git/config
> +
>  # Downloading up-to-date PO files.
>  
>  WEBLATE_REPO = https://framagit.org/tyreunom/guix-translations
> diff --git a/etc/git/gitconfig b/etc/git/gitconfig
> index c9ebdc8fa8..0b6984a05f 100644
> --- a/etc/git/gitconfig
> +++ b/etc/git/gitconfig
> @@ -1,5 +1,20 @@
> +[commit]
> +        gpgsign = true
> +
>  [diff "scheme"]
>         xfuncname = "^(\\(define.*)$"
>  
>  [diff "texinfo"]
>         xfuncname = "^@node[[:space:]]+([^,]+).*$"
> +
> +[format]
> +        useAutoBase = true
> +        thread = shallow
> +
> +[pull]
> +        rebase = true
> +
> +[sendemail]
> +        to = guix-patches@gnu.org
> +        headerCmd = etc/teams.scm cc-members-header-cmd
> +        thread = no

Otherwise LGTM.

Cheers

bug#58813: [PATCH v2 3/5] Makefile.am: Auto-configure Git on 'make'.

[Maxim Cournoyer]

Hi Liliana,

Liliana Marie Prikler <liliana.prikler@gmail.com> writes:

> Am Sonntag, dem 23.04.2023 um 22:29 -0400 schrieb Maxim Cournoyer:
>> This means we do not need to worry anymore about manually syncing the
>> pre-push git hook or the Guix-provided git configuration.

> IIUC we still need to invoke 'make .git/whatever' manually, and I'd
> actually like it to be that way, just with a nice phony target like
> 'make git-config' or 'make .git'.  WDYT?

Do, because the targets are added to nodist_noinst_DATA, they are
included in the default 'all' target (i.e., just invoking 'make' builds
them).

Because of that, a .PHONY target is not needed.  I think this is best,
since otherwise when etc/git/pre-push changed, you'd have to remember to
run 'make configure-git' for example.  It'd be error prone, and
easy to forget.

-- 
Thanks,
Maxim

bug#58813: [PATCH v2 3/5] Makefile.am: Auto-configure Git on 'make'.

[Josselin Poiret via Bug reports for GNU Guix]

[-- Attachment #1: Type: text/plain, Size: 804 bytes --]

Hi Maxim,

Only seeing this patchset now, but it seems great!

Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:

> +[commit]
> +        gpgsign = true
> +
>  [diff "scheme"]
>  	xfuncname = "^(\\(define.*)$"
>  
>  [diff "texinfo"]
>  	xfuncname = "^@node[[:space:]]+([^,]+).*$"
> +
> +[format]
> +        useAutoBase = true
> +        thread = shallow
> +
> +[pull]
> +        rebase = true
> +
> +[sendemail]
> +        to = guix-patches@gnu.org
> +        headerCmd = etc/teams.scm cc-members-header-cmd
> +        thread = no

Could we also consider adding format.forceinbodyfrom=true, so that
contributors whose From: gets rewritten by debbugs/mailman still have
the proper attribution without requiring manual action from committers?

Best,
-- 
Josselin Poiret

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 682 bytes --]

bug#58813: can't substitute etc/teams.scm command as doc suggests

[Maxim Cournoyer]

Hi,

Josselin Poiret <dev@jpoiret.xyz> writes:

> Hi Maxim,
>
> Only seeing this patchset now, but it seems great!
>
> Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:
>
>> +[commit]
>> +        gpgsign = true
>> +
>>  [diff "scheme"]
>>  	xfuncname = "^(\\(define.*)$"
>>  
>>  [diff "texinfo"]
>>  	xfuncname = "^@node[[:space:]]+([^,]+).*$"
>> +
>> +[format]
>> +        useAutoBase = true
>> +        thread = shallow
>> +
>> +[pull]
>> +        rebase = true
>> +
>> +[sendemail]
>> +        to = guix-patches@gnu.org
>> +        headerCmd = etc/teams.scm cc-members-header-cmd
>> +        thread = no
>
> Could we also consider adding format.forceinbodyfrom=true, so that
> contributors whose From: gets rewritten by debbugs/mailman still have
> the proper attribution without requiring manual action from committers?

Seems reasonable.  I've added it in, and have now pushed the series.
The upstream git commit hasn't been merged yet, but I've addressed all
their comments, and will continue doing so.

Closing, finally :-).  I'll push an associated news entry shortly.

-- 
Thanks,
Maxim

bug#58813: [PATCH v2 4/5] teams: Add a 'cc-mentors-header-cmd' action.

[Maxim Cournoyer]

* etc/teams.scm.in (main): Register a new "cc-mentors-header-cmd" action.
Document it.
---
 etc/teams.scm.in | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/etc/teams.scm.in b/etc/teams.scm.in
index 408db8b7d5..dec175f630 100644
--- a/etc/teams.scm.in
+++ b/etc/teams.scm.in
@@ -719,6 +719,9 @@ (define (main . args)
                  (list-members (find-team team-name) (current-output-port)
                                "X-Debbugs-Cc: "))
                (patch->teams patch-file)))
+    (("cc-mentors-header-cmd" patch-file)
+     (list-members (find-team "mentors") (current-output-port)
+                   "X-Debbugs-Cc: "))
     (("get-maintainer" patch-file)
      (apply main "list-members" (patch->teams patch-file)))
     (("list-teams" . args)
@@ -735,10 +738,12 @@ (define (main . args)
 Commands:
   cc <team-name>
       get git send-email flags for cc-ing <team-name>
-  cc-members <start> <end> | patch
+  cc-members <start> <end> | <patch>
       cc teams related to files changed between revisions or in a patch file
   cc-members-header-cmd <patch>
       cc-members variant for use with 'git send-email --header-cmd'
+  cc-mentors-header-cmd <patch>
+      command to use with 'git send-email --header-cmd' to notify mentors
   list-teams
       list teams and their members
   list-members <team-name>
-- 
2.39.2

bug#58813: [PATCH v2 5/5] doc: Simplify contributing section by automating git configuration.

[Maxim Cournoyer]

Fixes <https://issues.guix.gnu.org/58813>. No longer suggests to
splice the output of etc/teams.scm commands into the 'git send-email'
command line; this is now transparently handled by the Git
configuration, which is also automatic.

* doc/contributing.texi (Configuring Git): Streamline section, now automated
via Automake.
(Sending a Patch Series): Do not specify options configured as default by the
above.  Prefer long option names, for readability.
(Teams): Rewrite the examples to use --header-cmd.
(Commit Access): Refer to the Configuring Git section instead of detailing
manual steps.
---
 doc/contributing.texi | 104 ++++++++++++++----------------------------
 doc/guix.texi         |   2 +-
 2 files changed, 36 insertions(+), 70 deletions(-)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 73d1cd2648..b13531c5cc 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -1395,28 +1395,8 @@ Configuring Git
 use @command{git config --local}, or edit @file{.git/config} in the
 repository instead of @file{~/.gitconfig}.
 
-We provide some default settings in @file{etc/git/gitconfig} which
-modify how patches are generated, making them easier to read and apply.
-These settings can be applied by manually copying them to
-@file{.git/config} in your checkout, or by telling Git to include the
-whole file:
-
-@example
-git config --local include.path ../etc/git/gitconfig
-@end example
-
-From then on, any changes to @file{etc/git/gitconfig} would
-automatically take effect.
-
-Since the first patch in a series must be sent separately
-(@pxref{Sending a Patch Series}), it can also be helpful to tell
-@command{git format-patch} to handle the e-mail threading instead of
-@command{git send-email}:
-
-@example
-git config --local format.thread shallow
-git config --local sendemail.thread no
-@end example
+Other important Git configuration will automatically be configured when
+building the project (@pxref{Building from Git}).
 
 @node Sending a Patch Series
 @subsection Sending a Patch Series
@@ -1439,10 +1419,12 @@ Sending a Patch Series
 
 The following command will create a patch email from the latest commit,
 open it in your @var{EDITOR} or @var{VISUAL} for editing, and send it to
-the Guix mailing list to be reviewed and merged:
+the Guix mailing list to be reviewed and merged.  Assuming you have
+already configured Git according to @xref{Configuring Git}, you can
+simply use:
 
 @example
-$ git send-email -1 -a --base=auto --to=guix-patches@@gnu.org
+$ git send-email --annotate -1
 @end example
 
 @quotation Tip
@@ -1453,31 +1435,26 @@ Sending a Patch Series
 @url{https://git.savannah.gnu.org/cgit/guix.git}.
 
 @example
-git send-email -1 -a --base=auto \
-    --subject-prefix='PATCH core-updates' \
-    --to=guix-patches@@gnu.org
+git send-email --annotate --subject-prefix='PATCH core-updates' -1
 @end example
 @end quotation
 
 The patch email contains a three-dash separator line after the commit
 message.  You may ``annotate'' the patch with explanatory text by adding
 it under this line.  If you do not wish to annotate the email, you may
-drop the @option{-a} flag (which is short for @option{--annotate}).
-
-The @option{--base=auto} flag automatically adds a note at the bottom
-of the patch of the commit it was based on, making it easier for
-maintainers to rebase and merge your patch.
+drop the @option{--annotate} option.
 
 If you need to send a revised patch, don't resend it like this or send
 a ``fix'' patch to be applied on top of the last one; instead, use
-@command{git commit -a} or @url{https://git-rebase.io, @command{git rebase}}
-to modify the commit, and use the @email{@var{ISSUE_NUMBER}@@debbugs.gnu.org}
-address and the @option{-v} flag with @command{git send-email}.
+@command{git commit --amend} or @url{https://git-rebase.io,
+@command{git rebase}} to modify the commit, and use the
+@email{@var{ISSUE_NUMBER}@@debbugs.gnu.org} address and the @option{-v}
+flag with @command{git send-email}.
 
 @example
-$ git commit -a
-$ git send-email -1 -a --base=auto -v@var{REVISION} \
-      --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org
+$ git commit --amend
+$ git send-email --annotate -v@var{REVISION} \
+      --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org -1
 @end example
 
 @quotation Note
@@ -1494,14 +1471,14 @@ Sending a Patch Series
 @unnumberedsubsubsec Notifying Teams
 @anchor{Notifying Teams}
 @cindex teams
-The @file{etc/teams.scm} script may be used to notify all those who
-may be interested in your patch of its existence (@pxref{Teams}).
-Use @command{etc/teams.scm list-teams} to display all the teams,
-decide which team(s) your patch relates to, and use
-@command{etc/teams.scm cc} to output various @command{git send-email}
-flags which will notify the appropriate team members, or use
-@command{etc/teams.scm cc-members} to detect the appropriate teams
-automatically.
+If your git checkout has been correctly configured (@pxref{Configuring
+Git}), the @command{git send-email} command will automatically notify
+the appropriate team members, based on the scope of your changes.  This
+relies on the @file{etc/teams.scm} script, which can also be invoked
+manually if you do not use the preferred @command{git send-email}
+command to submit patches.  To list the available actions of the script,
+you can invoke it via the @command{etc/teams.scm help} command.  For
+more information regarding teams, see @xref{Teams}.
 
 @unnumberedsubsubsec Multiple Patches
 @anchor{Multiple Patches}
@@ -1528,9 +1505,7 @@ Sending a Patch Series
 that we can send the rest of the patches to.
 
 @example
-$ git send-email outgoing/0000-cover-letter.patch -a \
-      --to=guix-patches@@gnu.org \
-      $(etc/teams.scm cc-members ...)
+$ git send-email outgoing/0000-cover-letter.patch --annotate
 $ rm outgoing/0000-cover-letter.patch # we don't want to resend it!
 @end example
 
@@ -1542,9 +1517,7 @@ Sending a Patch Series
 can send the actual patches to the newly-created issue address.
 
 @example
-$ git send-email outgoing/*.patch \
-      --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org \
-      $(etc/teams.scm cc-members ...)
+$ git send-email outgoing/*.patch --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org
 $ rm -rf outgoing # we don't need these anymore
 @end example
 
@@ -1553,14 +1526,13 @@ Sending a Patch Series
 the patchset.
 
 @example
-$ git send-email -@var{NUMBER_COMMITS} \
-      -v@var{REVISION} --base=auto \
+$ git send-email -@var{NUMBER_COMMITS} -v@var{REVISION} \
       --to @var{ISSUE_NUMBER}@@debbugs.gnu.org
 @end example
 
-If need be, you may use @option{--cover-letter -a} to send another cover
-letter, e.g. for explaining what's changed since the last revision, and
-these changes are necessary.
+If need be, you may use @option{--cover-letter --annotate} to send
+another cover letter, e.g. for explaining what's changed since the last
+revision, and these changes are necessary.
 
 @node Teams
 @subsection Teams
@@ -1587,7 +1559,8 @@ Teams
 CC of a patch series:
 
 @example
-$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org $(./etc/teams.scm cc mentors) *.patch
+$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org \
+  --header-cmd='etc/teams.scm cc-mentors-header-cmd' *.patch
 @end example
 
 The appropriate team or teams can also be inferred from the modified
@@ -1596,7 +1569,7 @@ Teams
 
 @example
 $ guix shell -D guix
-[env]$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org $(./etc/teams.scm cc-members HEAD~2 HEAD) *.patch
+[env]$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org -2
 @end example
 
 @node Tracking Bugs and Patches
@@ -1831,16 +1804,9 @@ Commit Access
 make authenticate
 @end example
 
-You can prevent yourself from accidentally pushing unsigned or signed
-with the wrong key commits to Savannah by using the pre-push Git hook
-located at @file{etc/git/pre-push}:
-
-@example
-cp etc/git/pre-push .git/hooks/pre-push
-@end example
-
-It additionally calls @code{make check-channel-news} to be sure
-@file{news.scm} file is correct.
+To avoid accidentally pushing unsigned or signed with the wrong key
+commits to Savannah, make sure to configure Git according to
+@xref{Configuring Git}.
 
 @subsection Commit Policy
 
diff --git a/doc/guix.texi b/doc/guix.texi
index 9997aeb86e..e5f6c7e831 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -49,7 +49,7 @@
 Copyright @copyright{} 2017, 2021 Christine Lemmer-Webber@*
 Copyright @copyright{} 2017, 2018, 2019, 2020, 2021, 2022 Marius Bakke@*
 Copyright @copyright{} 2017, 2019, 2020, 2022 Hartmut Goebel@*
-Copyright @copyright{} 2017, 2019, 2020, 2021, 2022 Maxim Cournoyer@*
+Copyright @copyright{} 2017, 2019, 2020, 2021, 2022, 2023 Maxim Cournoyer@*
 Copyright @copyright{} 2017–2022 Tobias Geerinckx-Rice@*
 Copyright @copyright{} 2017 George Clemmer@*
 Copyright @copyright{} 2017 Andy Wingo@*
-- 
2.39.2

bug#58813: [PATCH 4/5] teams: Add a 'cc-mentors-header-cmd' action.

[Maxim Cournoyer]

* etc/teams.scm.in (main): Register a new "cc-mentors-header-cmd" action.
Document it.
---
 etc/teams.scm.in | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/etc/teams.scm.in b/etc/teams.scm.in
index 8203446446..50ac7f043f 100644
--- a/etc/teams.scm.in
+++ b/etc/teams.scm.in
@@ -725,6 +725,9 @@ (define (main . args)
                  (list-members (find-team team-name) (current-output-port)
                                "X-Debbugs-Cc: "))
                (patch->teams patch-file)))
+    (("cc-mentors-header-cmd" patch-file)
+     (list-members (find-team "mentors") (current-output-port)
+                   "X-Debbugs-Cc: "))
     (("configure-git")
      (configure-git))
     (("get-maintainer" patch-file)
@@ -743,10 +746,12 @@ (define (main . args)
 Commands:
   cc <team-name>
       get git send-email flags for cc-ing <team-name>
-  cc-members <start> <end> | patch
+  cc-members <start> <end> | <patch>
       cc teams related to files changed between revisions or in a patch file
   cc-members-header-cmd <patch>
       cc-members variant for use with 'git send-email --header-cmd'
+  cc-mentors-header-cmd <patch>
+      command to use with 'git send-email --header-cmd' to notify mentors
   configure-git
       automatically configure your git for Guix
   list-teams
-- 
2.39.2

bug#58813: [PATCH 5/5] doc: Simplify contributing section by automating git configuration.

[Maxim Cournoyer]

Fixes <https://issues.guix.gnu.org/58813>.  Instead of documenting all the
fine details of Git configuration, invite users to configure their checkout
with 'etc/teams configure-git'.  No longer suggests to splice the output of
etc/teams.scm commands into the 'git send-email' command line; this is now
transparently handled by the Git configuration.

* doc/contributing.texi (Configuring Git): Move configuration setup to
'etc/teams.scm configure-git'.
(Sending a Patch Series): Do not specify options configured as default by the
above.  Prefer long option names, for explicitness.
(Teams): Rewrite the examples to use --header-cmd.
(Commit Access): Refer to the Configuring Git section instead of detailing
manual steps.
---
 doc/contributing.texi | 102 +++++++++++++++---------------------------
 doc/guix.texi         |   2 +-
 2 files changed, 37 insertions(+), 67 deletions(-)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 73d1cd2648..fb72238487 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -1395,27 +1395,11 @@ Configuring Git
 use @command{git config --local}, or edit @file{.git/config} in the
 repository instead of @file{~/.gitconfig}.
 
-We provide some default settings in @file{etc/git/gitconfig} which
-modify how patches are generated, making them easier to read and apply.
-These settings can be applied by manually copying them to
-@file{.git/config} in your checkout, or by telling Git to include the
-whole file:
+To configure automatically your local Git checkout to use the
+recommended settings and hooks, run the following command once:
 
 @example
-git config --local include.path ../etc/git/gitconfig
-@end example
-
-From then on, any changes to @file{etc/git/gitconfig} would
-automatically take effect.
-
-Since the first patch in a series must be sent separately
-(@pxref{Sending a Patch Series}), it can also be helpful to tell
-@command{git format-patch} to handle the e-mail threading instead of
-@command{git send-email}:
-
-@example
-git config --local format.thread shallow
-git config --local sendemail.thread no
+etc/teams.scm configure-git
 @end example
 
 @node Sending a Patch Series
@@ -1439,10 +1423,12 @@ Sending a Patch Series
 
 The following command will create a patch email from the latest commit,
 open it in your @var{EDITOR} or @var{VISUAL} for editing, and send it to
-the Guix mailing list to be reviewed and merged:
+the Guix mailing list to be reviewed and merged.  Assuming you have
+already configured Git according to @xref{Configuring Git}, you can
+simply use:
 
 @example
-$ git send-email -1 -a --base=auto --to=guix-patches@@gnu.org
+$ git send-email --annotate -1
 @end example
 
 @quotation Tip
@@ -1453,31 +1439,26 @@ Sending a Patch Series
 @url{https://git.savannah.gnu.org/cgit/guix.git}.
 
 @example
-git send-email -1 -a --base=auto \
-    --subject-prefix='PATCH core-updates' \
-    --to=guix-patches@@gnu.org
+git send-email --annotate --subject-prefix='PATCH core-updates' -1
 @end example
 @end quotation
 
 The patch email contains a three-dash separator line after the commit
 message.  You may ``annotate'' the patch with explanatory text by adding
 it under this line.  If you do not wish to annotate the email, you may
-drop the @option{-a} flag (which is short for @option{--annotate}).
-
-The @option{--base=auto} flag automatically adds a note at the bottom
-of the patch of the commit it was based on, making it easier for
-maintainers to rebase and merge your patch.
+drop the @option{--annotate} option.
 
 If you need to send a revised patch, don't resend it like this or send
 a ``fix'' patch to be applied on top of the last one; instead, use
-@command{git commit -a} or @url{https://git-rebase.io, @command{git rebase}}
-to modify the commit, and use the @email{@var{ISSUE_NUMBER}@@debbugs.gnu.org}
-address and the @option{-v} flag with @command{git send-email}.
+@command{git commit --amend} or @url{https://git-rebase.io,
+@command{git rebase}} to modify the commit, and use the
+@email{@var{ISSUE_NUMBER}@@debbugs.gnu.org} address and the @option{-v}
+flag with @command{git send-email}.
 
 @example
-$ git commit -a
-$ git send-email -1 -a --base=auto -v@var{REVISION} \
-      --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org
+$ git commit --amend
+$ git send-email --annotate -v@var{REVISION} \
+      --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org -1
 @end example
 
 @quotation Note
@@ -1494,14 +1475,14 @@ Sending a Patch Series
 @unnumberedsubsubsec Notifying Teams
 @anchor{Notifying Teams}
 @cindex teams
-The @file{etc/teams.scm} script may be used to notify all those who
-may be interested in your patch of its existence (@pxref{Teams}).
-Use @command{etc/teams.scm list-teams} to display all the teams,
-decide which team(s) your patch relates to, and use
-@command{etc/teams.scm cc} to output various @command{git send-email}
-flags which will notify the appropriate team members, or use
-@command{etc/teams.scm cc-members} to detect the appropriate teams
-automatically.
+If your git checkout has been correctly configured (@pxref{Configuring
+Git}), the @command{git send-email} command will automatically notify
+the appropriate team members, based on the scope of your changes.  This
+relies on the @file{etc/teams.scm} script, which can also be invoked
+manually if you do not use the preferred @command{git send-email}
+command to submit patches.  To list the available actions of the script,
+you can invoke it via the @command{etc/teams.scm help} command.  For
+more information regarding teams, see @xref{Teams}.
 
 @unnumberedsubsubsec Multiple Patches
 @anchor{Multiple Patches}
@@ -1528,9 +1509,7 @@ Sending a Patch Series
 that we can send the rest of the patches to.
 
 @example
-$ git send-email outgoing/0000-cover-letter.patch -a \
-      --to=guix-patches@@gnu.org \
-      $(etc/teams.scm cc-members ...)
+$ git send-email outgoing/0000-cover-letter.patch --annotate
 $ rm outgoing/0000-cover-letter.patch # we don't want to resend it!
 @end example
 
@@ -1542,9 +1521,7 @@ Sending a Patch Series
 can send the actual patches to the newly-created issue address.
 
 @example
-$ git send-email outgoing/*.patch \
-      --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org \
-      $(etc/teams.scm cc-members ...)
+$ git send-email outgoing/*.patch --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org
 $ rm -rf outgoing # we don't need these anymore
 @end example
 
@@ -1553,14 +1530,13 @@ Sending a Patch Series
 the patchset.
 
 @example
-$ git send-email -@var{NUMBER_COMMITS} \
-      -v@var{REVISION} --base=auto \
+$ git send-email -@var{NUMBER_COMMITS} -v@var{REVISION} \
       --to @var{ISSUE_NUMBER}@@debbugs.gnu.org
 @end example
 
-If need be, you may use @option{--cover-letter -a} to send another cover
-letter, e.g. for explaining what's changed since the last revision, and
-these changes are necessary.
+If need be, you may use @option{--cover-letter --annotate} to send
+another cover letter, e.g. for explaining what's changed since the last
+revision, and these changes are necessary.
 
 @node Teams
 @subsection Teams
@@ -1587,7 +1563,8 @@ Teams
 CC of a patch series:
 
 @example
-$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org $(./etc/teams.scm cc mentors) *.patch
+$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org \
+  --header-cmd='etc/teams.scm cc-mentors-header-cmd' *.patch
 @end example
 
 The appropriate team or teams can also be inferred from the modified
@@ -1596,7 +1573,7 @@ Teams
 
 @example
 $ guix shell -D guix
-[env]$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org $(./etc/teams.scm cc-members HEAD~2 HEAD) *.patch
+[env]$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org -2
 @end example
 
 @node Tracking Bugs and Patches
@@ -1831,16 +1808,9 @@ Commit Access
 make authenticate
 @end example
 
-You can prevent yourself from accidentally pushing unsigned or signed
-with the wrong key commits to Savannah by using the pre-push Git hook
-located at @file{etc/git/pre-push}:
-
-@example
-cp etc/git/pre-push .git/hooks/pre-push
-@end example
-
-It additionally calls @code{make check-channel-news} to be sure
-@file{news.scm} file is correct.
+To avoid accidentally pushing unsigned or signed with the wrong key
+commits to Savannah, make sure to configure Git according to
+@xref{Configuring Git}.
 
 @subsection Commit Policy
 
diff --git a/doc/guix.texi b/doc/guix.texi
index 9997aeb86e..e5f6c7e831 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -49,7 +49,7 @@
 Copyright @copyright{} 2017, 2021 Christine Lemmer-Webber@*
 Copyright @copyright{} 2017, 2018, 2019, 2020, 2021, 2022 Marius Bakke@*
 Copyright @copyright{} 2017, 2019, 2020, 2022 Hartmut Goebel@*
-Copyright @copyright{} 2017, 2019, 2020, 2021, 2022 Maxim Cournoyer@*
+Copyright @copyright{} 2017, 2019, 2020, 2021, 2022, 2023 Maxim Cournoyer@*
 Copyright @copyright{} 2017–2022 Tobias Geerinckx-Rice@*
 Copyright @copyright{} 2017 George Clemmer@*
 Copyright @copyright{} 2017 Andy Wingo@*
-- 
2.39.2

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

[Simon Tournier]

From: Maxim Cournoyer <maxim.cournoyer@gmail.com>

Fixes <https://issues.guix.gnu.org/58813>.

* doc/contributing.texi (Sending a Patch Series): Adjust the examples to no
longer showcase broken command substitutions.
(Patch management using patman): New section about how to use Patman, with
examples.
---
 doc/contributing.texi | 111 ++++++++++++++++++++++++++++++++++++++++--
 doc/guix.texi         |   2 +-
 2 files changed, 108 insertions(+), 5 deletions(-)

Hi,

My proposal is to have Patch management using patman as a dedicated section.
This way, we keep the submission guidelines simple using good ol'
git-send-email.  And by being a dedicated section, it acts as the Perfect
Setup: that's a tool very handy for doing the patch management task.

WDYT?

Cheers,
simon


diff --git a/doc/contributing.texi b/doc/contributing.texi
index 61c05c2489..197f9719ba 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -1531,7 +1531,7 @@ that we can send the rest of the patches to.
 @example
 $ git send-email outgoing/0000-cover-letter.patch -a \
       --to=guix-patches@@gnu.org \
-      $(etc/teams.scm cc-members ...)
+      --cc=team-member1@@example.org --cc=team-member2@@example.org ...
 $ rm outgoing/0000-cover-letter.patch # we don't want to resend it!
 @end example
 
@@ -1545,7 +1545,7 @@ can send the actual patches to the newly-created issue address.
 @example
 $ git send-email outgoing/*.patch \
       --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org \
-      $(etc/teams.scm cc-members ...)
+      --cc=team-member1@@example.org --cc=team-member2@@example.org ...
 $ rm -rf outgoing # we don't need these anymore
 @end example
 
@@ -1588,18 +1588,121 @@ You can run the following command to have the @code{Mentors} team put in
 CC of a patch series:
 
 @example
-$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org $(./etc/teams.scm cc mentors) *.patch
+$ ./etc/teams.scm cc mentors
 @end example
 
+then note the @var{output} of the script.
+
+@example
+$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org @var{output} *.patch
+@end example
+
+Taking care to manually splice the @var{output} of the
+@file{etc/teams.scm} script into the command.
+
 The appropriate team or teams can also be inferred from the modified
 files.  For instance, if you want to send the two latest commits of the
 current Git repository to review, you can run:
 
 @example
 $ guix shell -D guix
-[env]$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org $(./etc/teams.scm cc-members HEAD~2 HEAD) *.patch
+[env]$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org @var{output} *.patch
+@end example
+
+@node Patch management using @command{patman}
+@subsection Patch management using @command{patman}
+@cindex patman patch manager
+@cindex patch management, via patman
+
+If you want something a bit higher level than @command{git send-email}
+to organize your patch submissions and take care of its various options
+for you, you may want to try the @command{patman} command, from the
+eponymous package.  Patman's help can be accessed via @samp{patman -H}
+or as an Info manual after installing the @code{u-boot-documentation}
+package (@pxref{Patman patch manager,,,u-boot,The U-Boot
+Documentation}).
+
+As manually stitching the output of the @file{etc/teams.scm} script in
+the @command{git send-email} command can get tedious; you may prefer to
+use Patman to automate this for you.  Its necessary basic configuration
+is already found at the root of the Guix repository, in the
+@file{.patman} file.  Another useful bit to have is a default
+destination for the @command{git send-email} command.  You can specify
+it in your repository-local Guix @file{.git/config} file with:
+
+@example
+[sendemail]
+        to = guix-patches@@gnu.org
+@end example
+
+To send a long series to Debbugs, the patches can be written to the
+current directory with:
+
+@example
+patman -n
+@end example
+
+The first patch should then be sent using @samp{git send-email
+0000-cover-letter.patch}, as explained earlier (@pxref{Multiple
+Patches}).
+
+After Debbugs has issued a unique bug email in reply to that initial
+patch submission, e.g. @email{NNNNN@@debbugs.gnu.org}, you can save this
+information into the top commit of your patch series (it doesn't matter
+which, but it's more convenient to amend it later when it's at the top)
+like so, via the Patman-specific @code{Series-to} git message tag:
+
+@example
+gnu: Add foo.
+
+* gnu/packages/dummy.scm: Add foo.
+
+Series-to: NNNNN@@debbugs.gnu.org
 @end example
 
+You can then send your series to that address with the right people
+automatically added in CC by simply issuing:
+
+@example
+patman
+@end example
+
+After addressing the first round of review comments, you can annotate a
+v2 patch series by adding these Patman-specific git message tags:
+
+@example
+gnu: Add foo.
+
+* gnu/packages/dummy.scm: Add foo.
+
+Series-to: NNNNN@@debbugs.gnu.org
+Series-version: 2
+Series-changes: 2
+- Factorized X into Y and Z
+@end example
+
+The @command{patman} command will then take care to automate the right
+@code{git send-email} command and produce patch annotations useful for
+the reviewers.
+
+After the review is complete, if you are the one merging your own
+changes, you should take care to strip any Patman git message tags.
+This can be done by writing the patches to the current directory with:
+
+@example
+patman -n
+@end example
+
+and then applying them to the main branch with:
+
+@example
+git am *.patch
+@end example
+
+For more information, run @samp{patman -H} or read its info manual,
+which can be installed with the @code{u-boot-documentation} package
+(@pxref{Patman patch manager,,,u-boot,The U-Boot Documentation}).
+
 @node Tracking Bugs and Patches
 @section Tracking Bugs and Patches
 
diff --git a/doc/guix.texi b/doc/guix.texi
index 6671ba9305..1fe03df3b7 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -49,7 +49,7 @@ Copyright @copyright{} 2017 humanitiesNerd@*
 Copyright @copyright{} 2017, 2021 Christine Lemmer-Webber@*
 Copyright @copyright{} 2017, 2018, 2019, 2020, 2021, 2022 Marius Bakke@*
 Copyright @copyright{} 2017, 2019, 2020, 2022 Hartmut Goebel@*
-Copyright @copyright{} 2017, 2019, 2020, 2021, 2022 Maxim Cournoyer@*
+Copyright @copyright{} 2017, 2019, 2020, 2021, 2022, 2023 Maxim Cournoyer@*
 Copyright @copyright{} 2017–2022 Tobias Geerinckx-Rice@*
 Copyright @copyright{} 2017 George Clemmer@*
 Copyright @copyright{} 2017 Andy Wingo@*

base-commit: 26e9725c54df48eda8282e6716a7581a7755f8f9
-- 
2.38.1

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

[Maxim Cournoyer]

Hi Simon,

Simon Tournier <zimon.toutoune@gmail.com> writes:

> From: Maxim Cournoyer <maxim.cournoyer@gmail.com>
>
> Fixes <https://issues.guix.gnu.org/58813>.
>
> * doc/contributing.texi (Sending a Patch Series): Adjust the examples to no
> longer showcase broken command substitutions.
> (Patch management using patman): New section about how to use Patman, with
> examples.
> ---
>  doc/contributing.texi | 111 ++++++++++++++++++++++++++++++++++++++++--
>  doc/guix.texi         |   2 +-
>  2 files changed, 108 insertions(+), 5 deletions(-)
>
> Hi,
>
> My proposal is to have Patch management using patman as a dedicated section.
> This way, we keep the submission guidelines simple using good ol'
> git-send-email.  And by being a dedicated section, it acts as the Perfect
> Setup: that's a tool very handy for doing the patch management task.
>
> WDYT?

Based on the other replies gathered so far, it seems there's little
excitement to learn yet another tool for patch management, so I think
I'll pursue the '--x-cmd' idea I already wrote about here, which would
allow integration directly with 'git send-email'.

-- 
Thanks,
Maxim

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

[Simon Tournier]

Hi,

On Tue, 07 Mar 2023 at 11:46, Maxim Cournoyer <maxim.cournoyer@gmail.com> wrote:

>> My proposal is to have Patch management using patman as a dedicated section.
>> This way, we keep the submission guidelines simple using good ol'
>> git-send-email.  And by being a dedicated section, it acts as the Perfect
>> Setup: that's a tool very handy for doing the patch management task.

> Based on the other replies gathered so far, it seems there's little
> excitement to learn yet another tool for patch management, so I think
> I'll pursue the '--x-cmd' idea I already wrote about here, which would
> allow integration directly with 'git send-email'.

Well, from my point of view, it is not exclusive. :-)

Let say I do not use the tools ’info’ and ’man’, but the manual has a
section dedicated to it [1].  Let say I am not excited by LaTex/TeX with
Guix, but the manual has a section dedicated to it [2].

And the “Perfect Setup” is about Emacs and links to Magit, other tools
that we could ask.  Maybe I am not excited by them.  Etc.

Anyway.

I still think this documentation for configuring ’patman’ about “Patch
management” is helpful.  I think it could be part of the manual.  If not
for reasons I am missing, at least this documentation should be included
in the Cookbook.

And from my point of view, if we say that [1,2] fits the manual, then
this dedicated section about “Patch management” also fits the manual.
If this dedicated section about “Patch management” also does not fit the
manual, then [1,2] neither. :-)

1: <https://guix.gnu.org/manual/devel/en/guix.html#Documentation>
2: <https://guix.gnu.org/manual/devel/en/guix.html#Using-TeX-and-LaTeX>

Cheers,
simon

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

[Liliana Marie Prikler]

Hi,

Am Dienstag, dem 07.03.2023 um 18:39 +0100 schrieb Simon Tournier:
> I still think this documentation for configuring ’patman’ about
> “Patch management” is helpful.  I think it could be part of the
> manual.  If not for reasons I am missing, at least this documentation
> should be included in the Cookbook.
There are two discussions here:
1. Should we "mandate" the use of patman?
2. Should we describe how to use patman for submitting patches to Guix?
I think most agree with the latter, but disagree with the former. 
Thus, whatever steps you add for the use with patman must be easily
enough replicated by people not using it, or else we risk low adoption
of best practices.

> And from my point of view, if we say that [1,2] fits the manual, then
> this dedicated section about “Patch management” also fits the manual.
> If this dedicated section about “Patch management” also does not fit
> the manual, then [1,2] neither. :-)
> 
> 1: <https://guix.gnu.org/manual/devel/en/guix.html#Documentation>
> 2:
> <https://guix.gnu.org/manual/devel/en/guix.html#Using-TeX-and-LaTeX>
I think [2] is distinct here in that it discusses Guix-specific quirks
when using TeX.

Cheers

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

[Simon Tournier]

Hi Liliana,

On Wed, 08 Mar 2023 at 06:29, Liliana Marie Prikler <liliana.prikler@gmail.com> wrote:
> Am Dienstag, dem 07.03.2023 um 18:39 +0100 schrieb Simon Tournier:

>> I still think this documentation for configuring ’patman’ about
>> “Patch management” is helpful.  I think it could be part of the
>> manual.  If not for reasons I am missing, at least this documentation
>> should be included in the Cookbook.
>
> There are two discussions here:
>
> 1. Should we "mandate" the use of patman?
> 2. Should we describe how to use patman for submitting patches to Guix?
>
> I think most agree with the latter, but disagree with the former. 
> Thus, whatever steps you add for the use with patman must be easily
> enough replicated by people not using it, or else we risk low adoption
> of best practices.

Well, I am not sure to understand “mandate”.  There is many tools that
appears in the Guix manual that are not “mandatory” but just
recommendations.  For instance, Emacs, emacs-geiser, emacs-debbugs, etc.
And even Git is not mandatory, maybe some people prefer Dulwich
(pure-Python implementation) or maybe others use ’gix’ (pure-Rust
implementation).  It would be fun to deal with Guix patches using gix. ;-)

So, I read “mandate” as recommend, hoping that I am not missing the
meaning you put behind the quoted mandate. :-)

About #1, I understand and I agree that the manual cannot recommend all
the tools on Earth and we have to make choices in order to keep it
clear, especially when newcomers is facing in the front of how to deal
with patches.

That’s why I also proposed to move this dedicated section about “Patch
management using patman” to the cookbook. :-)  It somehow answers #1 and
the item #2 is almost done.

Well, I do not have a strong opinion.  On a side note, because I am
lazy, if there is no pre-configuration that I can adapt, I will not try
patman.

Cheers,
simon

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

[Maxim Cournoyer]

Hi Simon,

Simon Tournier <zimon.toutoune@gmail.com> writes:

> Hi Liliana,
>
> On Wed, 08 Mar 2023 at 06:29, Liliana Marie Prikler <liliana.prikler@gmail.com> wrote:
>> Am Dienstag, dem 07.03.2023 um 18:39 +0100 schrieb Simon Tournier:
>
>>> I still think this documentation for configuring ’patman’ about
>>> “Patch management” is helpful.  I think it could be part of the
>>> manual.  If not for reasons I am missing, at least this documentation
>>> should be included in the Cookbook.
>>
>> There are two discussions here:
>>
>> 1. Should we "mandate" the use of patman?

I don't think this was ever in the discussion.  The patch series I sent
only hinted at a tool that can provide some further automation.  It's
not mandated (as in, required) at all.  git send-email works just fine
when manually pasting the output of 'etc/teams.scm cc-members
the.patch', and will continue to even if we mention the tool 'patman' in
conjunction.

[...]

> Well, I do not have a strong opinion.  On a side note, because I am
> lazy, if there is no pre-configuration that I can adapt, I will not try
> patman.

It's already there; see the .patman file at the root of the repo.
There's really not much to patman, it's a simple tool that does what it
does well (and already exists).

-- 
Thanks,
Maxim

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

[Simon Tournier]

Hi Maxim,

On Wed, 8 Mar 2023 at 17:26, Maxim Cournoyer <maxim.cournoyer@gmail.com> wrote:

> > Well, I do not have a strong opinion.  On a side note, because I am
> > lazy, if there is no pre-configuration that I can adapt, I will not try
> > patman.
>
> It's already there; see the .patman file at the root of the repo.
> There's really not much to patman, it's a simple tool that does what it
> does well (and already exists).

Yeah not much, still (1) someone needs to be aware of this not much
and (2) I find a value with the (not much) example of usage.

Anyway.  I understand if there is no consensus for the manual, so if
you do not bother, I will adapt the patch for the Cookbook.

Cheers,
simon

Bogus ‘etc/teams.scm’ usage recommendations?

[Ludovic Courtès]

Hello Guix!

The manual recommends this (info "(guix) Teams"):

  git send-email --to ISSUE_NUMBER@debbugs.gnu.org $(./etc/teams.scm cc mentors) *.patch

where:

--8<---------------cut here---------------start------------->8---
λ ./etc/teams.scm cc mentors
--add-header="X-Debbugs-Cc: rg@raghavgururajan.name" --add-header="X-Debbugs-Cc: zimon.toutoune@gmail.com" …
--8<---------------cut here---------------end--------------->8---

I believe this cannot work because the shell will split words on each
whitespace; IOW, the double quotes above do not have the desired effect.

The second issue is that passing ‘--add-header’ to ‘git send-email’
seems to have no effect.  AIUI, ‘git send-email’ passes those to ‘git
format-patch’, except that it has no reason to invoke it, right?

Maybe I’m missing something but it looks like we have documentation to
improve.  Thoughts?

Ludo’.

Re: Bogus ‘etc/teams.scm’ usage recommendations?

[Simon Tournier]

Hi Ludo,

On Tue, 03 Jan 2023 at 23:29, Ludovic Courtès <ludo@gnu.org> wrote:

> The manual recommends this (info "(guix) Teams"):
>
>   git send-email --to ISSUE_NUMBER@debbugs.gnu.org $(./etc/teams.scm cc mentors) *.patch
>
> where:
>
> --8<---------------cut here---------------start------------->8---
> λ ./etc/teams.scm cc mentors
> --add-header="X-Debbugs-Cc: rg@raghavgururajan.name" --add-header="X-Debbugs-Cc: zimon.toutoune@gmail.com" …
> --8<---------------cut here---------------end--------------->8---
>
> I believe this cannot work because the shell will split words on each
> whitespace; IOW, the double quotes above do not have the desired effect.

Well, IIUC, this part is tracked by #58813 [1].

1: <http://issues.guix.gnu.org/issue/58813>


Cheers,
simon

bug#58813: Bogus ‘etc/teams.scm’ usage recommendations?

[Maxim Cournoyer]

+CC 58813@debbugs.gnu.org

Hi,

Simon Tournier <zimon.toutoune@gmail.com> writes:

> Hi Ludo,
>
> On Tue, 03 Jan 2023 at 23:29, Ludovic Courtès <ludo@gnu.org> wrote:
>
>> The manual recommends this (info "(guix) Teams"):
>>
>>   git send-email --to ISSUE_NUMBER@debbugs.gnu.org $(./etc/teams.scm cc mentors) *.patch
>>
>> where:
>>
>> --8<---------------cut here---------------start------------->8---
>> λ ./etc/teams.scm cc mentors
>> --add-header="X-Debbugs-Cc: rg@raghavgururajan.name"
>> --add-header="X-Debbugs-Cc: zimon.toutoune@gmail.com" …
>> --8<---------------cut here---------------end--------------->8---
>>
>> I believe this cannot work because the shell will split words on each
>> whitespace; IOW, the double quotes above do not have the desired effect.

> Well, IIUC, this part is tracked by #58813 [1].
>
> 1: <http://issues.guix.gnu.org/issue/58813>

Indeed (CC'd).

I thought about not using whitespace in the generated output, but I'm
not sure if Debbugs or email clients in general would care, plus it's a
dirty fix.

With the recent patman integration merged (though do apply #60576 as a
fixup commit), I'm tempted to remove the mentions of git send-email
$(etc/teams.scm cc-members ...) and replace that by 'Further automation
of git send-email and etc/teams.scm is possible via the patman package'.

What do you think?

-- 
Thanks,
Maxim

Re: bug#58813: can't substitute etc/teams.scm command as doc suggests

[Ludovic Courtès]

Hi,

Maxim Cournoyer <maxim.cournoyer@gmail.com> skribis:

> Simon Tournier <zimon.toutoune@gmail.com> writes:
>
>> Hi Ludo,
>>
>> On Tue, 03 Jan 2023 at 23:29, Ludovic Courtès <ludo@gnu.org> wrote:
>>
>>> The manual recommends this (info "(guix) Teams"):
>>>
>>>   git send-email --to ISSUE_NUMBER@debbugs.gnu.org $(./etc/teams.scm cc mentors) *.patch
>>>
>>> where:
>>>
>>> --8<---------------cut here---------------start------------->8---
>>> λ ./etc/teams.scm cc mentors
>>> --add-header="X-Debbugs-Cc: rg@raghavgururajan.name"
>>> --add-header="X-Debbugs-Cc: zimon.toutoune@gmail.com" …
>>> --8<---------------cut here---------------end--------------->8---
>>>
>>> I believe this cannot work because the shell will split words on each
>>> whitespace; IOW, the double quotes above do not have the desired effect.
>
>> Well, IIUC, this part is tracked by #58813 [1].
>>
>> 1: <http://issues.guix.gnu.org/issue/58813>
>
> Indeed (CC'd).
>
> I thought about not using whitespace in the generated output, but I'm
> not sure if Debbugs or email clients in general would care, plus it's a
> dirty fix.

Right.

How about just outputting a line like:

  X-Debbugs-Cc: maxim@example.org, ludo@example.org

that people would paste in their cover letter?

How do Linux’s scripts work?

> With the recent patman integration merged (though do apply #60576 as a
> fixup commit), I'm tempted to remove the mentions of git send-email
> $(etc/teams.scm cc-members ...) and replace that by 'Further automation
> of git send-email and etc/teams.scm is possible via the patman package'.
>
> What do you think?

This is the first time I hear about patman.  :-)

The “Submitting Patches” section mentions ‘git send-email’; I don’t
think this is about to change, is it?

Thanks,
Ludo’.

Re: bug#58813: can't substitute etc/teams.scm command as doc suggests

[Maxim Cournoyer]

Hi Ludovic,

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

> Hi,
>
> Maxim Cournoyer <maxim.cournoyer@gmail.com> skribis:
>
>> Simon Tournier <zimon.toutoune@gmail.com> writes:
>>
>>> Hi Ludo,
>>>
>>> On Tue, 03 Jan 2023 at 23:29, Ludovic Courtès <ludo@gnu.org> wrote:
>>>
>>>> The manual recommends this (info "(guix) Teams"):
>>>>
>>>>   git send-email --to ISSUE_NUMBER@debbugs.gnu.org $(./etc/teams.scm cc mentors) *.patch
>>>>
>>>> where:
>>>>
>>>> --8<---------------cut here---------------start------------->8---
>>>> λ ./etc/teams.scm cc mentors
>>>> --add-header="X-Debbugs-Cc: rg@raghavgururajan.name"
>>>> --add-header="X-Debbugs-Cc: zimon.toutoune@gmail.com" …
>>>> --8<---------------cut here---------------end--------------->8---
>>>>
>>>> I believe this cannot work because the shell will split words on each
>>>> whitespace; IOW, the double quotes above do not have the desired effect.
>>
>>> Well, IIUC, this part is tracked by #58813 [1].
>>>
>>> 1: <http://issues.guix.gnu.org/issue/58813>
>>
>> Indeed (CC'd).
>>
>> I thought about not using whitespace in the generated output, but I'm
>> not sure if Debbugs or email clients in general would care, plus it's a
>> dirty fix.
>
> Right.
>
> How about just outputting a line like:
>
>   X-Debbugs-Cc: maxim@example.org, ludo@example.org
>
> that people would paste in their cover letter?

Yes, that's better.

> How do Linux’s scripts work?

I think the scripts just print stuff at the terminal and expect the user
to copy paste.  Patman can be used to provide automation on top of that.

>> With the recent patman integration merged (though do apply #60576 as a
>> fixup commit), I'm tempted to remove the mentions of git send-email
>> $(etc/teams.scm cc-members ...) and replace that by 'Further automation
>> of git send-email and etc/teams.scm is possible via the patman package'.
>>
>> What do you think?
>
> This is the first time I hear about patman.  :-)
>
> The “Submitting Patches” section mentions ‘git send-email’; I don’t
> think this is about to change, is it?

It wouldn't change; patman would be hinted at briefly with a reference
to its documentation (info '(u-boot) Patman patch manager' from the
u-boot-documentation package) as a nice way to stay organize with
submissions and automate a few things on top of git send-email.

-- 
Thanks,
Maxim

Re: bug#58813: can't substitute etc/teams.scm command as doc suggests

[Simon Tournier]

Hi,

On Mon, 09 Jan 2023 at 15:52, Maxim Cournoyer <maxim.cournoyer@gmail.com> wrote:

> It wouldn't change; patman would be hinted at briefly with a reference
> to its documentation (info '(u-boot) Patman patch manager' from the
> u-boot-documentation package) as a nice way to stay organize with
> submissions and automate a few things on top of git send-email.

Is it possible to read online patman documentation?  I am not able to
find one.  Moreover, it could ease the adoption if a minimal sample of
such configuration is provided.  A minimal out of the box configuration
as starter.

On my side, if I have to do more than just click to read documentation,
then I give up.  And then, if I have to parse lengthy documentation,
then it depends on my motivation but it is also possible that I give
up–the well-known RTFM trap.  In other words, I am lazy. :-)

Cheers,
simon

Re: bug#58813: can't substitute etc/teams.scm command as doc suggests

[Maxim Cournoyer]

Hi Simon,

Simon Tournier <zimon.toutoune@gmail.com> writes:

> Hi,
>
> On Mon, 09 Jan 2023 at 15:52, Maxim Cournoyer <maxim.cournoyer@gmail.com> wrote:
>
>> It wouldn't change; patman would be hinted at briefly with a reference
>> to its documentation (info '(u-boot) Patman patch manager' from the
>> u-boot-documentation package) as a nice way to stay organize with
>> submissions and automate a few things on top of git send-email.
>
> Is it possible to read online patman documentation?  I am not able to
> find one.

It's developed as part of U-Boot and available at
https://u-boot.readthedocs.io/en/latest/develop/patman.html.  It's
generated from the same sources as the info manual from
u-boot-documentation referenced above.

> Moreover, it could ease the adoption if a minimal sample of
> such configuration is provided.  A minimal out of the box configuration
> as starter.

No configuration is required other than the .patman file already checked
in Guix.

> On my side, if I have to do more than just click to read documentation,
> then I give up.  And then, if I have to parse lengthy documentation,
> then it depends on my motivation but it is also possible that I give
> up–the well-known RTFM trap.  In other words, I am lazy. :-)

The 'Patman patch manager' section is relatively compact; I read it from
the comfort of Emacs ;-).  There's also some alternative short text
available as 'patman -H' if you are in a hurry.

-- 
Thanks,
Maxim

Re: bug#58813: can't substitute etc/teams.scm command as doc suggests

[Simon Tournier]

Hi Maxim,

On mer., 11 janv. 2023 at 22:00, Maxim Cournoyer <maxim.cournoyer@gmail.com> wrote:

> It's developed as part of U-Boot and available at
> https://u-boot.readthedocs.io/en/latest/develop/patman.html.  It's
> generated from the same sources as the info manual from
> u-boot-documentation referenced above.

Oh thanks!  I do not know why I did not found it when using my favorite
search engine. :-)

>> On my side, if I have to do more than just click to read documentation,
>> then I give up.  And then, if I have to parse lengthy documentation,
>> then it depends on my motivation but it is also possible that I give
>> up–the well-known RTFM trap.  In other words, I am lazy. :-)
>
> The 'Patman patch manager' section is relatively compact; I read it from
> the comfort of Emacs ;-).  There's also some alternative short text
> available as 'patman -H' if you are in a hurry.

Well, I still think that examples about how to use it are worth and will
help for adoption. :-)

For instance, this section of the manual [1] describes how to use
git-format-patch and git-send-email with details applied to Guix
examples.  It appears to me better than just pointing [2] and [3]. ;-)


1: <https://guix.gnu.org/manual/devel/en/guix.html#Sending-a-Patch-Series>
2: <https://git-scm.com/docs/git-format-patch>
3: <https://git-scm.com/docs/git-send-email>

Cheers,
simon