bartronx7/guix
1
0
Fork 0
mirror of https://codeberg.org/guix/guix.git synced 2026-01-25 03:55:08 -06:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc: Remove “Sending a Patch Series” section.

Browse source 
* doc/contributing.texi (Sending a Patch Series): Remove.

Change-Id: I8f15c4385b24cecc6a8f1bd13c2065d2a267e5b1
This commit is contained in:
Ludovic Courtès 2026-01-23 10:17:46 +01:00
parent e3d6091b26
commit 73acc2c9bf
No known key found for this signature in database
GPG key ID: 090B11993D9AEBB5
1 changed files with 0 additions and 161 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

161
doc/contributing.texi
View file

@ -2129,7 +2129,6 @@ guix pull --url=/path/to/your/checkout --profile=/tmp/guix.master --disable-auth
@menu @menu
* Configuring Git:: * Configuring Git::
* Sending a Patch Series::
@end menu @end menu
@node Configuring Git @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 @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. 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 @node Tracking Bugs and Changes
@section Tracking Bugs and Changes @section Tracking Bugs and Changes