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

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

[( via Guix-patches via]

This patch significantly expands the "Sending a Patch Series" section
of "Contributing".

( (1):
  doc: contributing: Expand "Sending a Patch Series".

 doc/contributing.texi | 83 ++++++++++++++++++++++++++++++++++++-------
 1 file changed, 71 insertions(+), 12 deletions(-)

-- 
2.38.0

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

[( via Guix-patches via]

* doc/contributing.texi: Expand on sending patches and using
  git send-email.
---
 doc/contributing.texi | 83 ++++++++++++++++++++++++++++++++++++-------
 1 file changed, 71 insertions(+), 12 deletions(-)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 4b1eed1cb1..c7a2dd09e7 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -1409,19 +1409,78 @@ git config --local sendemail.thread no
 @anchor{Sending a Patch Series}
 @cindex patch series
 @cindex @code{git send-email}
+The @code{git send-email} and @code{git format-patch} commands allow you
+to send your commits in email form to a mailing list, to be reviewed and
+applied, and they are the recommended way to submit contributions to Guix.
+When you send the first revision of a patch series, it's best to use
+@code{git format-patch --cover-letter}.
 
-When sending a patch series (e.g., using @code{git send-email}), please
-first send one message to @email{guix-patches@@gnu.org}, and then send
-subsequent patches to @email{@var{NNN}@@debbugs.gnu.org} to make sure
-they are kept together.  See
-@uref{https://debbugs.gnu.org/Advanced.html, the Debbugs documentation}
-for more information.  You can install @command{git send-email} with
-@command{guix install git:send-email}.
-@c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html
-
-To maximize the chances that you patch series is reviewed, the preferred
-submission way is to use the @code{etc/teams.scm} script to notify the
-appropriate team members (@pxref{Teams}).
+@example
+$ git format-patch -$N -o outgoing --cover-letter
+@end example
+
+@quotation Note
+The @code{git send-email} command is provided by the @code{send-email}
+output of the @code{git} package, i.e. @code{git:send-email}.
+@end quotation
+
+This command makes patches out of the last @var{N} commits, and writes
+them to @code{.patch} files in @code{outgoing/}, along with an automatically
+generated cover letter.  We can then send the cover letter to the Guix
+mailing list.
+
+@example
+$ git send-email outgoing/0000-cover-letter.patch -a --to guix-patches@@gnu.org
+@end example
+
+Note the @code{-a} flag; this pops up your editor so that you can fill in
+the patchset subject line and blurb with whatever explanatory text you
+feel is appropriate.  Note the automatically generated shortlog and
+diffstat below the blurb, which help to give potential reviewers an
+overview of the patchset.
+
+At some point, the Debbugs mailer will reply to your cover letter mail
+with an acknowledgement, which contains the issue number of your patchset.
+You should now send the rest of the patches to this issue thread, using
+the @code{@var{ISSUE_NUMBER}@@debbugs.gnu.org} address.
+
+@example
+$ rm outgoing/0000-cover-letter.patch # Don't resend the cover letter!
+$ git send-email outgoing/*.patch --to ISSUE_NUMBER@@debbugs.gnu.org
+$ rm -rf outgoing # We're done with the patch files now.
+@end example
+
+After a moment, your patches should appear at
+@url{https://issues.guix.gnu.org/@var{ISSUE_NUMBER}} and
+@url{https://debbugs.gnu.org/@var{ISSUE_NUMBER}}.
+
+@quotation Note
+You should @strong{never} send all your patches to
+@code{guix-patches@@gnu.org} at once, as this will create an issue for
+each individual patch you send!  If you do accidentally do this, though,
+it's not a massive problem, as Debbugs supports merging issues.
+@end quotation
+
+The use of the @code{etc/teams.scm} script to notify the appropriate team
+members (@pxref{Teams}) is recommended when submitting patches, to maximize
+the chances of your patch series being reviewed quickly.
+
+To incorporate a reviewer's suggestions, use @code{git rebase -i} to amend
+the commits, as demonstrated @url{https://git-rebase.io, here}, and send a
+second patch series with a @code{-v2} tag.
+
+@example
+$ git send-email -$N -v2 --to ISSUE_NUMBER@@debbugs.gnu.org
+@end example
+
+Note that since we already have an issue on Debbugs for our patchset,
+there's no need for the intermediate @code{git format-patch} step. Of
+course, to send a third patchset, you amy use @code{-v3}, to send a fourth,
+@code{-v4}, and so on.
+
+If need be, you may use @code{--cover-letter -a} to send another cover letter,
+e.g. for explaining what's changed since the last revision, and these changes
+are necessary.
 
 @unnumberedsubsec Teams
 @anchor{Teams}
-- 
2.38.0

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

[zimoun]

Hi,

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


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

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


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

Here…

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

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


[...]

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

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


[...]

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

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



Cheers,
simon

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

[( via Guix-patches via]

Heya Simon,

On Thu Oct 20, 2022 at 9:56 AM BST, zimoun wrote:
> On mer., 19 oct. 2022 at 23:00, "\( via Guix-patches" via <guix-patches@gnu.org> wrote:
> > +@example
> > +$ git format-patch -$N -o outgoing --cover-letter
> > +@end example
>
> Here…
>
> > +
> > +@quotation Note
> > +The @code{git send-email} command is provided by the @code{send-email}
> > +output of the @code{git} package, i.e. @code{git:send-email}.
> > +@end quotation
> > +
> > +This command makes patches out of the last @var{N} commits, and writes
> > +them to @code{.patch} files in @code{outgoing/}, along with an automatically
> > +generated cover letter.  We can then send the cover letter to the Guix
> > +mailing list.
>
> …or in these explanations, I would also suggest the option ’--base’; as
> recommended by item #1 in subsection «Submitting Patches».

Oh, cool, I didn't know about ``--base'' :) I'll add that in.

> > +At some point, the Debbugs mailer will reply to your cover letter mail
> > +with an acknowledgement, which contains the issue number of your patchset.
> > +You should now send the rest of the patches to this issue thread, using
> > +the @code{@var{ISSUE_NUMBER}@@debbugs.gnu.org} address.
>
> I agree that ISSUE_NUMBER is a better name than NNN or else.  Therefore,
> maybe it could be worth to also tweak it in the section Teams.

Okay.

> > +The use of the @code{etc/teams.scm} script to notify the appropriate team
> > +members (@pxref{Teams}) is recommended when submitting patches, to maximize
> > +the chances of your patch series being reviewed quickly.
>
> I would advertise about Teams early in this section.  Maybe in the first
> paragraph.

Alright!

    -- (

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

[( via Guix-patches via]

* doc/contributing.texi: Expand on sending patches and using
  git send-email.
---
 doc/contributing.texi | 120 ++++++++++++++++++++++++++++++------------
 1 file changed, 86 insertions(+), 34 deletions(-)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 4b1eed1cb1..650d3430fb 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -1149,15 +1149,6 @@ Before submitting a patch that adds or modifies a package definition,
 please run through this check list:
 
 @enumerate
-@cindex @code{git format-patch}
-@cindex @code{git-format-patch}
-@item
-When generating your patches with @code{git format-patch} or @code{git
-send-email}, we recommend using the option @code{--base=}, perhaps with
-the value @code{auto}.  This option adds a note to the patch stating
-which commit the patch is based on.  This helps reviewers understand how
-to apply and review your patches.
-
 @item
 If the authors of the packaged software provide a cryptographic
 signature for the release tarball, make an effort to verify the
@@ -1343,18 +1334,6 @@ a subject, if your patch is to be applied on a branch other than
 @code{master}, say @code{core-updates}, specify it in the subject like
 @samp{[PATCH core-updates] @dots{}}.
 
-@quotation Tip
-To add a prefix to the subject of your patch, you may use the
-@option{--subject-prefix} option of the @command{git format-patch} or
-@command{git send-email} commands, for example:
-@example
-git send-email --subject-prefix='PATCH core-updates' \
-  --to=guix-patches@@gnu.org -1
-@end example
-For more information, run @samp{man git-format-patch} and @samp{man
-git-send-email}.
-@end quotation
-
 You may use your email client or the @command{git send-email} command
 (@pxref{Sending a Patch Series}).  We prefer to get patches in plain
 text messages, either inline or as MIME attachments.  You are advised to
@@ -1409,19 +1388,92 @@ git config --local sendemail.thread no
 @anchor{Sending a Patch Series}
 @cindex patch series
 @cindex @code{git send-email}
+The @command{git send-email} and @command{git format-patch} commands allow
+you to send your commits in email form to a mailing list, to be reviewed
+and applied, and they are the recommended way to submit contributions to
+Guix. When you send the first revision of a patch series, it's best to use
+@command{git format-patch --cover-letter}.
+
+@example
+$ git format-patch -$N -o outgoing --cover-letter --base=HEAD~$N
+@end example
+
+@quotation Note
+The @command{git send-email} command is provided by the @code{send-email}
+output of the @code{git} package, i.e. @code{git:send-email}.
+@end quotation
+
+This command makes patches out of the last @var{N} commits, and writes
+them to @file{*.patch} files in @file{outgoing/}, along with an
+automatically generated cover letter.  The @option{--base=HEAD~$N} option
+adds @code{base-commit: @var{COMMIT}} to the bottom of the first email.
+
+We can now send the cover letter to the Guix mailing list, using
+@command{git send-email}.
+
+@example
+$ git send-email outgoing/0000-cover-letter.patch -a --to guix-patches@@gnu.org
+@end example
+
+Note the @option{-a} flag; this pops up your editor so that you can fill
+in the patchset subject line and blurb with whatever explanatory text you
+feel is appropriate.  Note the automatically generated shortlog and
+diffstat below the blurb, which help to give potential reviewers an
+overview of the patchset.
+
+@quotation Tip
+To add a prefix to the subject of your patch, you may use the
+@option{--subject-prefix} option.
+
+@example
+git format-patch -$N -o outgoing \
+    --subject-prefix='PATCH core-updates' \
+    --base=auto --cover-letter
+@end example
+@end quotation
+
+The use of the @file{etc/teams.scm} script to notify the appropriate team
+members (@pxref{Teams}) is recommended when submitting patches, to maximize
+the chances of your patch series being reviewed quickly.
+
+At some point, the Debbugs mailer will reply to your cover letter mail
+with an acknowledgement, which contains the issue number of your patchset.
+You should now send the rest of the patches to this issue thread, using
+the @email{@var{ISSUE_NUMBER}@@debbugs.gnu.org} address.
+
+@example
+$ rm outgoing/0000-cover-letter.patch # Don't resend the cover letter!
+$ git send-email outgoing/*.patch --to ISSUE_NUMBER@@debbugs.gnu.org
+$ rm -rf outgoing # We're done with the patch files now.
+@end example
+
+After a moment, your patches should appear at
+@url{https://issues.guix.gnu.org/@var{ISSUE_NUMBER}} and
+@url{https://debbugs.gnu.org/@var{ISSUE_NUMBER}}.
+
+@quotation Note
+You should @strong{never} send all your patches to
+@email{guix-patches@@gnu.org} at once, as this will create an issue for
+each individual patch you send!  If you do accidentally do this, though,
+it's not a massive problem, as Debbugs supports merging issues.
+@end quotation
+
+To incorporate a reviewer's suggestions, use @command{git rebase -i} to
+amendthe commits, as demonstrated @url{https://git-rebase.io, here}, and
+send a second patch series with a @option{-v2} tag.
+
+@example
+$ git send-email -$N -v2 --base=auto --to ISSUE_NUMBER@@debbugs.gnu.org
+@end example
 
-When sending a patch series (e.g., using @code{git send-email}), please
-first send one message to @email{guix-patches@@gnu.org}, and then send
-subsequent patches to @email{@var{NNN}@@debbugs.gnu.org} to make sure
-they are kept together.  See
-@uref{https://debbugs.gnu.org/Advanced.html, the Debbugs documentation}
-for more information.  You can install @command{git send-email} with
-@command{guix install git:send-email}.
-@c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html
+Note that since we already have an issue on Debbugs for our patchset,
+there's no need for the intermediate @command{git format-patch} step. Of
+course, to send a third patchset, you amy use @option{-v3}, to send a
+fourth, @option{-v4}, and so on.
 
-To maximize the chances that you patch series is reviewed, the preferred
-submission way is to use the @code{etc/teams.scm} script to notify the
-appropriate team members (@pxref{Teams}).
+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.
 
 @unnumberedsubsec Teams
 @anchor{Teams}
@@ -1448,7 +1500,7 @@ You can run the following command to have the @code{Mentors} team put in
 CC of a patch series:
 
 @example
-$ git send-email --to XXX@@debbugs.gnu.org $(./etc/teams.scm cc mentors) *.patch
+$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org $(./etc/teams.scm cc mentors) *.patch
 @end example
 
 The appropriate team or teams can also be inferred from the modified
@@ -1457,7 +1509,7 @@ current Git repository to review, you can run:
 
 @example
 $ guix shell -D guix
-[env]$ git send-email --to XXX@@debbugs.gnu.org $(./etc/teams.scm cc-members HEAD~2 HEAD) *.patch
+[env]$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org $(./etc/teams.scm cc-members HEAD~2 HEAD) *.patch
 @end example
 
 @node Tracking Bugs and Patches

base-commit: 88746cd80bc56212ae7922c0fa1cd9a18e44c3bb
-- 
2.38.0

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

[Liliana Marie Prikler]

Am Donnerstag, dem 20.10.2022 um 15:13 +0100 schrieb (:
> * doc/contributing.texi: Expand on sending patches and using
>   git send-email.
> ---
>  doc/contributing.texi | 120 ++++++++++++++++++++++++++++++----------
> --
>  1 file changed, 86 insertions(+), 34 deletions(-)
> 
> diff --git a/doc/contributing.texi b/doc/contributing.texi
> index 4b1eed1cb1..650d3430fb 100644
> --- a/doc/contributing.texi
> +++ b/doc/contributing.texi
> @@ -1149,15 +1149,6 @@ Before submitting a patch that adds or
> modifies a package definition,
>  please run through this check list:
>  
>  @enumerate
> -@cindex @code{git format-patch}
> -@cindex @code{git-format-patch}
> -@item
> -When generating your patches with @code{git format-patch} or
> @code{git
> -send-email}, we recommend using the option @code{--base=}, perhaps
> with
> -the value @code{auto}.  This option adds a note to the patch stating
> -which commit the patch is based on.  This helps reviewers understand
> how
> -to apply and review your patches.
> -
>  @item
>  If the authors of the packaged software provide a cryptographic
>  signature for the release tarball, make an effort to verify the
> @@ -1343,18 +1334,6 @@ a subject, if your patch is to be applied on a
> branch other than
>  @code{master}, say @code{core-updates}, specify it in the subject
> like
>  @samp{[PATCH core-updates] @dots{}}.
>  
> -@quotation Tip
> -To add a prefix to the subject of your patch, you may use the
> -@option{--subject-prefix} option of the @command{git format-patch}
> or
> -@command{git send-email} commands, for example:
> -@example
> -git send-email --subject-prefix='PATCH core-updates' \
> -  --to=guix-patches@@gnu.org -1
> -@end example
> -For more information, run @samp{man git-format-patch} and @samp{man
> -git-send-email}.
> -@end quotation
> -
>  You may use your email client or the @command{git send-email}
> command
>  (@pxref{Sending a Patch Series}).  We prefer to get patches in plain
>  text messages, either inline or as MIME attachments.  You are
> advised to
> @@ -1409,19 +1388,92 @@ git config --local sendemail.thread no
>  @anchor{Sending a Patch Series}
>  @cindex patch series
>  @cindex @code{git send-email}
> +The @command{git send-email} and @command{git format-patch} commands
> allow
> +you to send your commits in email form to a mailing list, to be
> reviewed
> +and applied, and they are the recommended way to submit
> contributions to
> +Guix. When you send the first revision of a patch series, it's best
> to use
> +@command{git format-patch --cover-letter}.
> +
> +@example
> +$ git format-patch -$N -o outgoing --cover-letter --base=HEAD~$N
> +@end example
> +
> +@quotation Note
> +The @command{git send-email} command is provided by the @code{send-
> email}
> +output of the @code{git} package, i.e. @code{git:send-email}.
> +@end quotation
> +
> +This command makes patches out of the last @var{N} commits, and
> writes
> +them to @file{*.patch} files in @file{outgoing/}, along with an
> +automatically generated cover letter.  The @option{--base=HEAD~$N}
> option
> +adds @code{base-commit: @var{COMMIT}} to the bottom of the first
> email.
> +
> +We can now send the cover letter to the Guix mailing list, using
> +@command{git send-email}.
> +
> +@example
> +$ git send-email outgoing/0000-cover-letter.patch -a --to guix-
> patches@@gnu.org
> +@end example
> +
> +Note the @option{-a} flag; this pops up your editor so that you can
> fill
> +in the patchset subject line and blurb with whatever explanatory
> text you
> +feel is appropriate.  Note the automatically generated shortlog and
> +diffstat below the blurb, which help to give potential reviewers an
> +overview of the patchset.
> +
> +@quotation Tip
> +To add a prefix to the subject of your patch, you may use the
> +@option{--subject-prefix} option.
> +
> +@example
> +git format-patch -$N -o outgoing \
> +    --subject-prefix='PATCH core-updates' \
> +    --base=auto --cover-letter
> +@end example
> +@end quotation
> +
> +The use of the @file{etc/teams.scm} script to notify the appropriate
> team
> +members (@pxref{Teams}) is recommended when submitting patches, to
> maximize
> +the chances of your patch series being reviewed quickly.
I think you should also elaborate how this script is to be used.

> +At some point, the Debbugs mailer will reply to your cover letter
> mail
> +with an acknowledgement, which contains the issue number of your
> patchset.
> +You should now send the rest of the patches to this issue thread,
> using
> +the @email{@var{ISSUE_NUMBER}@@debbugs.gnu.org} address.
> +
> +@example
> +$ rm outgoing/0000-cover-letter.patch # Don't resend the cover
> letter!
> +$ git send-email outgoing/*.patch --to ISSUE_NUMBER@@debbugs.gnu.org
> +$ rm -rf outgoing # We're done with the patch files now.
> +@end example
> +
> +After a moment, your patches should appear at
> +@url{https://issues.guix.gnu.org/@var{ISSUE_NUMBER}} and
> +@url{https://debbugs.gnu.org/@var{ISSUE_NUMBER}}.
> +
> +@quotation Note
> +You should @strong{never} send all your patches to
> +@email{guix-patches@@gnu.org} at once, as this will create an issue
> for
> +each individual patch you send!  If you do accidentally do this,
> though,
> +it's not a massive problem, as Debbugs supports merging issues.
> +@end quotation
Perhaps 
  @quotation Caution
  Do @strong{not} send all your patches at once, as this will create an
  issue for each individual patch.  While Debbugs supports merging 
  issues, some interfaces (e.g. Mumi) still treat them as separate
  in certain ways, which can lower or exaggerate visibility and annoy
  reviewers.
  @end quotation

> +To incorporate a reviewer's suggestions, use @command{git rebase -i}
> to
> +amendthe commits, as demonstrated @url{https://git-rebase.io, here},
> and
amend the
> +send a second patch series with a @option{-v2} tag.
> +
> +@example
> +$ git send-email -$N -v2 --base=auto --to
> ISSUE_NUMBER@@debbugs.gnu.org
> +@end example
>  
> -When sending a patch series (e.g., using @code{git send-email}),
> please
> -first send one message to @email{guix-patches@@gnu.org}, and then
> send
> -subsequent patches to @email{@var{NNN}@@debbugs.gnu.org} to make
> sure
> -they are kept together.  See
> -@uref{https://debbugs.gnu.org/Advanced.html, the Debbugs
> documentation}
> -for more information.  You can install @command{git send-email} with
> -@command{guix install git:send-email}.
> -@c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html
> +Note that since we already have an issue on Debbugs for our
> patchset,
> +there's no need for the intermediate @command{git format-patch}
> step. Of
> +course, to send a third patchset, you amy use @option{-v3}, to send
> a
> +fourth, @option{-v4}, and so on.
>  
> -To maximize the chances that you patch series is reviewed, the
> preferred
> -submission way is to use the @code{etc/teams.scm} script to notify
> the
> -appropriate team members (@pxref{Teams}).
> +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.
>  
>  @unnumberedsubsec Teams
>  @anchor{Teams}
> @@ -1448,7 +1500,7 @@ You can run the following command to have the
> @code{Mentors} team put in
>  CC of a patch series:
>  
>  @example
> -$ git send-email --to XXX@@debbugs.gnu.org $(./etc/teams.scm cc
> mentors) *.patch
> +$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org
> $(./etc/teams.scm cc mentors) *.patch
>  @end example
>  
>  The appropriate team or teams can also be inferred from the modified
> @@ -1457,7 +1509,7 @@ current Git repository to review, you can run:
>  
>  @example
>  $ guix shell -D guix
> -[env]$ git send-email --to XXX@@debbugs.gnu.org $(./etc/teams.scm
> cc-members HEAD~2 HEAD) *.patch
> +[env]$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org
> $(./etc/teams.scm cc-members HEAD~2 HEAD) *.patch
>  @end example
>  
>  @node Tracking Bugs and Patches
> 
> base-commit: 88746cd80bc56212ae7922c0fa1cd9a18e44c3bb
Also, this series makes it look as though we're only considering multi-
patch series.  Is the simple case of a single patch still covered?  I'd
perhaps organize this along these lines:
- Sending a single patch
- Notifying your senpais via etc/teams
- Sending a multi-patch series
Please don't take these headings too literally ;)

Cheers

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

[( via Guix-patches via]

On Sat Oct 22, 2022 at 12:21 PM BST, Liliana Marie Prikler wrote:
> Also, this series makes it look as though we're only considering multi-
> patch series.  Is the simple case of a single patch still covered?

$ git format-patch -1 --cover-letter --base=auto -o outgoing

works fine for a single patch.  In my opinion, you should send a cover
letter for every set of patches, even if the set only contains a single
patch.

    -- (

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

[Liliana Marie Prikler]

Am Samstag, dem 22.10.2022 um 12:30 +0100 schrieb (:
> On Sat Oct 22, 2022 at 12:21 PM BST, Liliana Marie Prikler wrote:
> > Also, this series makes it look as though we're only considering
> > multi-
> > patch series.  Is the simple case of a single patch still covered?
> 
> $ git format-patch -1 --cover-letter --base=auto -o outgoing
> 
> works fine for a single patch.  In my opinion, you should send a
> cover letter for every set of patches, even if the set only contains
> a single patch.
> 
>     -- (
I kindly disagree.  With single patches, you can add notes below the
dashed line and send less bytes over avian carriers.

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

[( via Guix-patches via]

* doc/contributing.texi: Expand on sending patches and using
  git send-email.
---
 doc/contributing.texi | 173 +++++++++++++++++++++++++++++++++---------
 1 file changed, 136 insertions(+), 37 deletions(-)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 4b1eed1cb1..9770018521 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -1138,8 +1138,8 @@ This mailing list is backed by a Debbugs instance, which allows us to
 keep track of submissions (@pxref{Tracking Bugs and Patches}).  Each
 message sent to that mailing list gets a new tracking number assigned;
 people can then follow up on the submission by sending email to
-@code{@var{NNN}@@debbugs.gnu.org}, where @var{NNN} is the tracking
-number (@pxref{Sending a Patch Series}).
+@code{@var{ISSUE_NUMBER}@@debbugs.gnu.org}, where @var{ISSUE_NUMBER} is
+the tracking number (@pxref{Sending a Patch Series}).
 
 Please write commit logs in the ChangeLog format (@pxref{Change Logs,,,
 standards, GNU Coding Standards}); you can check the commit history for
@@ -1149,15 +1149,6 @@ Before submitting a patch that adds or modifies a package definition,
 please run through this check list:
 
 @enumerate
-@cindex @code{git format-patch}
-@cindex @code{git-format-patch}
-@item
-When generating your patches with @code{git format-patch} or @code{git
-send-email}, we recommend using the option @code{--base=}, perhaps with
-the value @code{auto}.  This option adds a note to the patch stating
-which commit the patch is based on.  This helps reviewers understand how
-to apply and review your patches.
-
 @item
 If the authors of the packaged software provide a cryptographic
 signature for the release tarball, make an effort to verify the
@@ -1343,18 +1334,6 @@ a subject, if your patch is to be applied on a branch other than
 @code{master}, say @code{core-updates}, specify it in the subject like
 @samp{[PATCH core-updates] @dots{}}.
 
-@quotation Tip
-To add a prefix to the subject of your patch, you may use the
-@option{--subject-prefix} option of the @command{git format-patch} or
-@command{git send-email} commands, for example:
-@example
-git send-email --subject-prefix='PATCH core-updates' \
-  --to=guix-patches@@gnu.org -1
-@end example
-For more information, run @samp{man git-format-patch} and @samp{man
-git-send-email}.
-@end quotation
-
 You may use your email client or the @command{git send-email} command
 (@pxref{Sending a Patch Series}).  We prefer to get patches in plain
 text messages, either inline or as MIME attachments.  You are advised to
@@ -1367,7 +1346,7 @@ acknowledgement with the assigned tracking number. Future acknowledgements
 should not be delayed.
 
 When a bug is resolved, please close the thread by sending an email to
-@email{@var{NNN}-done@@debbugs.gnu.org}.
+@email{@var{ISSUE_NUMBER}-done@@debbugs.gnu.org}.
 
 @node Configuring Git
 @subsection Configuring Git
@@ -1409,19 +1388,139 @@ git config --local sendemail.thread no
 @anchor{Sending a Patch Series}
 @cindex patch series
 @cindex @code{git send-email}
+@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.
+
+@quotation Note
+The @command{git send-email} command is provided by the @code{send-email}
+output of the @code{git} package, i.e. @code{git:send-email}.
+@end quotation
+
+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:
+
+@example
+$ git send-email -1 -a --base=auto --to=guix-patches@@gnu.org
+@end example
+
+@quotation Tip
+To add a prefix to the subject of your patch, you may use the
+@option{--subject-prefix} option.  The Guix project uses this to
+specify that the patch is intended for a branch or repository
+other than the @code{master} branch of
+@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
+@end example
+@end quotation
 
-When sending a patch series (e.g., using @code{git send-email}), please
-first send one message to @email{guix-patches@@gnu.org}, and then send
-subsequent patches to @email{@var{NNN}@@debbugs.gnu.org} to make sure
-they are kept together.  See
-@uref{https://debbugs.gnu.org/Advanced.html, the Debbugs documentation}
-for more information.  You can install @command{git send-email} with
-@command{guix install git:send-email}.
-@c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html
+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.
+
+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}.
+
+@example
+$ git commit -a
+$ git send-email -1 -a --base=auto -v @var{REVISION} \
+      --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org
+@end example
+
+You can find out @var{ISSUE_NUMBER} either by searching on the mumi
+interface at @url{issues.guix.gnu.org} for the name of your patch or
+reading the acknowledgement email sent automatically by Debbugs in
+reply to incoming bugs and patches, which contains the bug number.
+
+@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.
+
+@unnumberedsubsubsec Multiple Patches
+@anchor{Multiple Patches}
+@cindex cover letter
+While @command{git send-email} alone will suffice for a single
+patch, an unfortunate flaw in Debbugs means you need to be more
+careful when sending multiple patches: if you send them all to the
+@email{guix-patches@@gnu.org} address, a new issue will be created
+for each patch!
+
+When sending a series of patches, it's best to send a Git ``cover
+letter'' first, to give reviewers an overview of the patch series.
+We can create a directory called @file{outgoing} containing both
+our patch series and a cover letter called @file{0000-cover-letter.patch}
+with @command{git format-patch}.
+
+@example
+$ git format-patch -@var{NUMBER_COMMITS} -o outgoing \
+      --cover-letter --base=auto
+@end example
+
+We can now send @emph{just} the cover letter to the
+@email{guix-patches@@gnu.org} address, which will create an issue
+that we can send the rest of the patches to.
+
+@example
+$ git send-email outgoing/0000-cover-letter.patch -a \
+      --to=guix-patches@@debbugs.gnu.org \
+      $(etc/teams.scm cc-members ...)
+$ rm outgoing/0000-cover-letter.patch # we don't want to resend it!
+@end example
+
+Ensure you edit the email to add an appropriate subject line and
+blurb before sending it.  Note the automatically generated shortlog
+and diffstat below the blurb.
+
+Once the Debbugs mailer has replied to your cover letter email, you
+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 ...)
+$ rm -rf outgoing # we don't need these anymore
+@end example
+
+Thankfully, this @command{git format-patch} dance is not necessary
+to send an amended patch series, since an issue already exists for
+the patchset.
+
+@example
+$ git send-email -@var{NUMBER_COMMITS} \
+      -v@var{REVISION} --base=auto \
+      --to @var{ISSUE_NUMBER}@@debbugs.gnu.org
+@end example
 
-To maximize the chances that you patch series is reviewed, the preferred
-submission way is to use the @code{etc/teams.scm} script to notify the
-appropriate team members (@pxref{Teams}).
+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.
 
 @unnumberedsubsec Teams
 @anchor{Teams}
@@ -1448,7 +1547,7 @@ You can run the following command to have the @code{Mentors} team put in
 CC of a patch series:
 
 @example
-$ git send-email --to XXX@@debbugs.gnu.org $(./etc/teams.scm cc mentors) *.patch
+$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org $(./etc/teams.scm cc mentors) *.patch
 @end example
 
 The appropriate team or teams can also be inferred from the modified
@@ -1457,7 +1556,7 @@ current Git repository to review, you can run:
 
 @example
 $ guix shell -D guix
-[env]$ git send-email --to XXX@@debbugs.gnu.org $(./etc/teams.scm cc-members HEAD~2 HEAD) *.patch
+[env]$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org $(./etc/teams.scm cc-members HEAD~2 HEAD) *.patch
 @end example
 
 @node Tracking Bugs and Patches

base-commit: 88746cd80bc56212ae7922c0fa1cd9a18e44c3bb
-- 
2.38.0

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

[Liliana Marie Prikler]

Am Dienstag, dem 25.10.2022 um 19:42 +0100 schrieb (:
> * doc/contributing.texi: Expand on sending patches and using
>   git send-email.
> ---
>  doc/contributing.texi | 173 +++++++++++++++++++++++++++++++++-------
> --
>  1 file changed, 136 insertions(+), 37 deletions(-)
> 
> diff --git a/doc/contributing.texi b/doc/contributing.texi
> index 4b1eed1cb1..9770018521 100644
> --- a/doc/contributing.texi
> +++ b/doc/contributing.texi
> @@ -1138,8 +1138,8 @@ This mailing list is backed by a Debbugs
> instance, which allows us to
>  keep track of submissions (@pxref{Tracking Bugs and Patches}).  Each
>  message sent to that mailing list gets a new tracking number
> assigned;
>  people can then follow up on the submission by sending email to
> -@code{@var{NNN}@@debbugs.gnu.org}, where @var{NNN} is the tracking
> -number (@pxref{Sending a Patch Series}).
> +@code{@var{ISSUE_NUMBER}@@debbugs.gnu.org}, where @var{ISSUE_NUMBER}
> is
> +the tracking number (@pxref{Sending a Patch Series}).
>  
>  Please write commit logs in the ChangeLog format (@pxref{Change
> Logs,,,
>  standards, GNU Coding Standards}); you can check the commit history
> for
> @@ -1149,15 +1149,6 @@ Before submitting a patch that adds or
> modifies a package definition,
>  please run through this check list:
>  
>  @enumerate
> -@cindex @code{git format-patch}
> -@cindex @code{git-format-patch}
> -@item
> -When generating your patches with @code{git format-patch} or
> @code{git
> -send-email}, we recommend using the option @code{--base=}, perhaps
> with
> -the value @code{auto}.  This option adds a note to the patch stating
> -which commit the patch is based on.  This helps reviewers understand
> how
> -to apply and review your patches.
> -
>  @item
>  If the authors of the packaged software provide a cryptographic
>  signature for the release tarball, make an effort to verify the
> @@ -1343,18 +1334,6 @@ a subject, if your patch is to be applied on a
> branch other than
>  @code{master}, say @code{core-updates}, specify it in the subject
> like
>  @samp{[PATCH core-updates] @dots{}}.
>  
> -@quotation Tip
> -To add a prefix to the subject of your patch, you may use the
> -@option{--subject-prefix} option of the @command{git format-patch}
> or
> -@command{git send-email} commands, for example:
> -@example
> -git send-email --subject-prefix='PATCH core-updates' \
> -  --to=guix-patches@@gnu.org -1
> -@end example
> -For more information, run @samp{man git-format-patch} and @samp{man
> -git-send-email}.
> -@end quotation
> -
>  You may use your email client or the @command{git send-email}
> command
>  (@pxref{Sending a Patch Series}).  We prefer to get patches in plain
>  text messages, either inline or as MIME attachments.  You are
> advised to
> @@ -1367,7 +1346,7 @@ acknowledgement with the assigned tracking
> number. Future acknowledgements
>  should not be delayed.
>  
>  When a bug is resolved, please close the thread by sending an email
> to
> -@email{@var{NNN}-done@@debbugs.gnu.org}.
> +@email{@var{ISSUE_NUMBER}-done@@debbugs.gnu.org}.
>  
>  @node Configuring Git
>  @subsection Configuring Git
> @@ -1409,19 +1388,139 @@ git config --local sendemail.thread no
>  @anchor{Sending a Patch Series}
>  @cindex patch series
>  @cindex @code{git send-email}
> +@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.
> +
> +@quotation Note
> +The @command{git send-email} command is provided by the @code{send-
> email}
> +output of the @code{git} package, i.e. @code{git:send-email}.
> +@end quotation
> +
> +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:
> +
> +@example
> +$ git send-email -1 -a --base=auto --to=guix-patches@@gnu.org
> +@end example
> +
> +@quotation Tip
> +To add a prefix to the subject of your patch, you may use the
> +@option{--subject-prefix} option.  The Guix project uses this to
> +specify that the patch is intended for a branch or repository
> +other than the @code{master} branch of
> +@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
> +@end example
> +@end quotation
>  
> -When sending a patch series (e.g., using @code{git send-email}),
> please
> -first send one message to @email{guix-patches@@gnu.org}, and then
> send
> -subsequent patches to @email{@var{NNN}@@debbugs.gnu.org} to make
> sure
> -they are kept together.  See
> -@uref{https://debbugs.gnu.org/Advanced.html, the Debbugs
> documentation}
> -for more information.  You can install @command{git send-email} with
> -@command{guix install git:send-email}.
> -@c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html
> +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.
> +
> +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}.
> +
> +@example
> +$ git commit -a
> +$ git send-email -1 -a --base=auto -v @var{REVISION} \
> +      --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org
> +@end example
> +
> +You can find out @var{ISSUE_NUMBER} either by searching on the mumi
> +interface at @url{issues.guix.gnu.org} for the name of your patch or
> +reading the acknowledgement email sent automatically by Debbugs in
> +reply to incoming bugs and patches, which contains the bug number.
> +
> +@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.
> +
> +@unnumberedsubsubsec Multiple Patches
> +@anchor{Multiple Patches}
> +@cindex cover letter
> +While @command{git send-email} alone will suffice for a single
> +patch, an unfortunate flaw in Debbugs means you need to be more
> +careful when sending multiple patches: if you send them all to the
> +@email{guix-patches@@gnu.org} address, a new issue will be created
> +for each patch!
> +
> +When sending a series of patches, it's best to send a Git ``cover
> +letter'' first, to give reviewers an overview of the patch series.
> +We can create a directory called @file{outgoing} containing both
> +our patch series and a cover letter called @file{0000-cover-
> letter.patch}
> +with @command{git format-patch}.
> +
> +@example
> +$ git format-patch -@var{NUMBER_COMMITS} -o outgoing \
> +      --cover-letter --base=auto
> +@end example
> +
> +We can now send @emph{just} the cover letter to the
> +@email{guix-patches@@gnu.org} address, which will create an issue
> +that we can send the rest of the patches to.
> +
> +@example
> +$ git send-email outgoing/0000-cover-letter.patch -a \
> +      --to=guix-patches@@debbugs.gnu.org \
> +      $(etc/teams.scm cc-members ...)
> +$ rm outgoing/0000-cover-letter.patch # we don't want to resend it!
> +@end example
> +
> +Ensure you edit the email to add an appropriate subject line and
> +blurb before sending it.  Note the automatically generated shortlog
> +and diffstat below the blurb.
> +
> +Once the Debbugs mailer has replied to your cover letter email, you
> +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 ...)
> +$ rm -rf outgoing # we don't need these anymore
> +@end example
> +
> +Thankfully, this @command{git format-patch} dance is not necessary
> +to send an amended patch series, since an issue already exists for
> +the patchset.
> +
> +@example
> +$ git send-email -@var{NUMBER_COMMITS} \
> +      -v@var{REVISION} --base=auto \
> +      --to @var{ISSUE_NUMBER}@@debbugs.gnu.org
> +@end example
>  
> -To maximize the chances that you patch series is reviewed, the
> preferred
> -submission way is to use the @code{etc/teams.scm} script to notify
> the
> -appropriate team members (@pxref{Teams}).
> +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.
>  
>  @unnumberedsubsec Teams
>  @anchor{Teams}
> @@ -1448,7 +1547,7 @@ You can run the following command to have the
> @code{Mentors} team put in
>  CC of a patch series:
>  
>  @example
> -$ git send-email --to XXX@@debbugs.gnu.org $(./etc/teams.scm cc
> mentors) *.patch
> +$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org
> $(./etc/teams.scm cc mentors) *.patch
>  @end example
>  
>  The appropriate team or teams can also be inferred from the modified
> @@ -1457,7 +1556,7 @@ current Git repository to review, you can run:
>  
>  @example
>  $ guix shell -D guix
> -[env]$ git send-email --to XXX@@debbugs.gnu.org $(./etc/teams.scm
> cc-members HEAD~2 HEAD) *.patch
> +[env]$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org
> $(./etc/teams.scm cc-members HEAD~2 HEAD) *.patch
>  @end example
>  
>  @node Tracking Bugs and Patches
> 
> base-commit: 88746cd80bc56212ae7922c0fa1cd9a18e44c3bb
LGTM.

Also CC'd zimoun

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

[( via Guix-patches via]

Heya,

On Tue Oct 25, 2022 at 8:18 PM BST, Liliana Marie Prikler wrote:
> LGTM.

\o/

Thanks for the review! (Simon too :))

    -- (

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

[zimoun]

Hi,

On mar., 25 oct. 2022 at 21:18, Liliana Marie Prikler <liliana.prikler@gmail.com> wrote:
> Am Dienstag, dem 25.10.2022 um 19:42 +0100 schrieb (:
>> * doc/contributing.texi: Expand on sending patches and using
>>   git send-email.
>> ---
>>  doc/contributing.texi | 173 +++++++++++++++++++++++++++++++++-------
>> --
>>  1 file changed, 136 insertions(+), 37 deletions(-)
>> 
>> diff --git a/doc/contributing.texi b/doc/contributing.texi
>> index 4b1eed1cb1..9770018521 100644
>> --- a/doc/contributing.texi
>> +++ b/doc/contributing.texi

[...]

> LGTM.

Well, I do not find where I did a minor comment and I do not remember
what it was.  It means it was not so much important.  And I can propose
it later. :-)

LGTM!  Liliana, feel free to push. :-)


Cheers,
simon

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

[zimoun]

Hi Liliana,

On sam., 22 oct. 2022 at 14:20, Liliana Marie Prikler <liliana.prikler@gmail.com> wrote:

>> works fine for a single patch.  In my opinion, you should send a
>> cover letter for every set of patches, even if the set only contains
>> a single patch.

> I kindly disagree.  With single patches, you can add notes below the
> dashed line and send less bytes over avian carriers.

Well, the section is a recommendation for helping in contributions.
Therefore, I also think it is a good idea to recommend to start by a
cover letter even for single patch.  It does not mean that some other
workflows are not possible. :-)

Cheers,
simon