| Message ID | 20221019220048.24290-1-paren@disroot.org |
|---|---|
| State | New |
| Headers | show |
| Series | doc: contributing: Expand "Sending a Patch Series". | expand |
| Context | Check | Description |
|---|---|---|
| cbaines/comparison | success | View comparision |
| cbaines/git-branch | success | View Git branch |
| cbaines/applying patch | success | View Laminar job |
| cbaines/issue | success | View issue |
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
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! -- (
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}