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

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

[Maxim Cournoyer]

Hi Simon,

Simon Tournier  writes:

> Hi Liliana,
>
> On Wed, 08 Mar 2023 at 06:29, Liliana Marie Prikler 
>  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 Liliana,

On Wed, 08 Mar 2023 at 06:29, Liliana Marie Prikler  
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.

[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: 
> 2:
> 
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,

On Tue, 07 Mar 2023 at 11:46, Maxim Cournoyer  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: 
2: 

Cheers,
simon

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

[Maxim Cournoyer]

Hi Simon,

Simon Tournier  writes:

> From: Maxim Cournoyer 
>
> Fixes .
>
> * 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]

From: Maxim Cournoyer 

Fixes .

* 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/-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/-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
+-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{N@@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: N@@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: N@@debbugs.gnu.org
+Series-version: 2
+Series-changes: 2
+- Factorized X into Y and Z
+@end example
+
+The @