From 73acc2c9bf54667db067ad42d3e96cd94d76fe00 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ludovic=20Court=C3=A8s?= Date: Fri, 23 Jan 2026 10:17:46 +0100 Subject: [PATCH] =?UTF-8?q?doc:=20Remove=20=E2=80=9CSending=20a=20Patch=20?= =?UTF-8?q?Series=E2=80=9D=20section.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/contributing.texi (Sending a Patch Series): Remove. Change-Id: I8f15c4385b24cecc6a8f1bd13c2065d2a267e5b1 --- doc/contributing.texi | 161 ------------------------------------------ 1 file changed, 161 deletions(-) diff --git a/doc/contributing.texi b/doc/contributing.texi index 4ffb8e9dc87..c07db28f939 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -2129,7 +2129,6 @@ guix pull --url=/path/to/your/checkout --profile=/tmp/guix.master --disable-auth @menu * Configuring Git:: -* Sending a Patch Series:: @end menu @node Configuring Git @@ -2156,166 +2155,6 @@ changes was already submitted for review. If you have a @file{commit-msg} hook of your own you would like to use with Guix, you can place it under the @file{.git/hooks/commit-msg.d/} directory. -@node Sending a Patch Series -@subsection Sending a Patch Series -@cindex patch series -@cindex @code{git send-email} -@cindex @code{git format-patch} - -@quotation Warning -This section is about contributing code by sending patches by email. -This option is supported until December 31st, 2025, but we recommend -getting familiar with the @dfn{pull request} workflow, which will become -the norm after that date. @xref{Submitting Patches}, for more info. -@end quotation - -@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. Assuming you have -already configured Git according to @xref{Configuring Git}, you can -simply use: - -@example -$ git send-email --annotate -1 -@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://codeberg.org/guix/guix.git}. - -@example -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{--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 --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 --amend -$ git send-email --annotate -v@var{REVISION} \ - --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org -1 -@end example - -@quotation Note -Due to an apparent bug in @command{git send-email}, -@option{-v @var{REVISION}} (with the space) will not work; you -@emph{must} use @option{-v@var{REVISION}}. -@end quotation - -You can find out @var{ISSUE_NUMBER} either by searching on the mumi -interface at @url{https://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 -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, @pxref{Teams}. - -@quotation Note -On foreign distros, you might have to use @command{./pre-inst-env git -send-email} for @file{etc/teams.scm} to work. -@end quotation - -@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 -@end example - -@quotation Note -@code{git format-patch} accepts a wide range of -@uref{https://git-scm.com/docs/gitrevisions, revision range} specifiers. -For example, if you are working in a branch, you could select all commits -in your branch starting at @code{master}. - -@example -$ git format-patch master..@var{MY_BRANCH} -o outgoing \ - --cover-letter -@end example -@end quotation - -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 --annotate -$ 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 -$ 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} \ - --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org -@end example - -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 why these changes are necessary. - @node Tracking Bugs and Changes @section Tracking Bugs and Changes