Next: Teams, Previous: Configurando o Git, Up: Enviando patches [Contents][Index]
The git send-email
command is the best way to send both single
patches and patch series (see Multiple Patches) to the Guix mailing
list. Sending patches as email attachments may make them difficult to
review in some mail clients, and git diff
does not store commit
metadata.
Nota: The
git send-email
command is provided by thesend-email
output of thegit
package, i.e.git:send-email
.
The following command will create a patch email from the latest commit, open it in your EDITOR or VISUAL for editing, and send it to the Guix mailing list to be reviewed and merged:
$ git send-email -1 -a --base=auto --to=guix-patches@gnu.org
Tip: To add a prefix to the subject of your patch, you may use the --subject-prefix option. The Guix project uses this to specify that the patch is intended for a branch or repository other than the
master
branch of https://git.savannah.gnu.org/cgit/guix.git.git send-email -1 -a --base=auto \ --subject-prefix='PATCH core-updates' \ --to=guix-patches@gnu.org
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 -a flag (which is short for --annotate).
The --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
git commit -a
or git rebase
to modify the commit, and use the
ISSUE_NUMBER@debbugs.gnu.org address and the -v flag
with git send-email
.
$ git commit -a $ git send-email -1 -a --base=auto -v REVISION \ --to=ISSUE_NUMBER@debbugs.gnu.org
You can find out ISSUE_NUMBER either by searching on the mumi interface at 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.
The etc/teams.scm script may be used to notify all those who may be
interested in your patch of its existence (see Teams). Use
etc/teams.scm list-teams
to display all the teams, decide which
team(s) your patch relates to, and use etc/teams.scm cc
to output
various git send-email
flags which will notify the appropriate
team members, or use etc/teams.scm cc-members
to detect the
appropriate teams automatically.
While 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 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 outgoing containing both our patch series and a
cover letter called 0000-cover-letter.patch with git
format-patch
.
$ git format-patch -NUMBER_COMMITS -o outgoing \ --cover-letter --base=auto
We can now send just the cover letter to the guix-patches@gnu.org address, which will create an issue that we can send the rest of the patches to.
$ 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!
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.
$ git send-email outgoing/*.patch \ --to=ISSUE_NUMBER@debbugs.gnu.org \ $(etc/teams.scm cc-members ...) $ rm -rf outgoing # we don't need these anymore
Thankfully, this git format-patch
dance is not necessary to send
an amended patch series, since an issue already exists for the patchset.
$ git send-email -NUMBER_COMMITS \ -vREVISION --base=auto \ --to ISSUE_NUMBER@debbugs.gnu.org
If need be, you may use --cover-letter -a to send another cover letter, e.g. for explaining what’s changed since the last revision, and these changes are necessary.
Next: Teams, Previous: Configurando o Git, Up: Enviando patches [Contents][Index]