mirror of
https://codeberg.org/guix/guix.git
synced 2026-01-25 03:55:08 -06:00
doc: Remove “Sending a Patch Series” section.
* doc/contributing.texi (Sending a Patch Series): Remove. Change-Id: I8f15c4385b24cecc6a8f1bd13c2065d2a267e5b1
This commit is contained in:
Ludovic Courtès
parent
e3d6091b26
commit
73acc2c9bf
1 changed files with 0 additions and 161 deletions
|
|
@ -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
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue