Одиночные патчи

Команда git send-email - лучший способ отправки как отдельных патчей, так и серий патчей (see Multiple Patches) в список рассылки Guix. Отправка патчей в виде вложений по электронной почте может затруднить их просмотр в некоторых почтовых клиентах, а команда git diff не хранит метаданные коммитов.

Примечание: The git send-email command is provided by the send-email output of the git package, i.e. git:send-email.

Следующая команда создаст письмо с патчем из последнего коммита, откроет его в вашем EDITOR или VISUAL для редактирования и отправит его в список рассылки Guix для рассмотрения и объединения. Если вы уже настроили Git согласно See Конфигурирование Git, вы можете просто использовать:

$ git send-email --annotate -1

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 --annotate --subject-prefix='PATCH core-updates' -1

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 --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 git commit --amend 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 --amend
$ git send-email --annotate -vREVISION \
      --to=ISSUE_NUMBER@debbugs.gnu.org -1

Примечание: Due to an apparent bug in git send-email, -v REVISION (with the space) will not work; you must use -vREVISION.

You can find out ISSUE_NUMBER either by searching on the mumi interface at 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.

Notifying Teams

If your git checkout has been correctly configured (see Конфигурирование Git), the git send-email command will automatically notify the appropriate team members, based on the scope of your changes. This relies on the etc/teams.scm script, which can also be invoked manually if you do not use the preferred git send-email command to submit patches. To list the available actions of the script, you can invoke it via the etc/teams.scm help command. For more information regarding teams, see Teams.

Примечание: On foreign distros, you might have to use ./pre-inst-env git send-email for etc/teams.scm to work.

Multiple Patches

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

Примечание: git format-patch accepts a wide range of revision range specifiers. For example, if you are working in a branch, you could select all commits in your branch starting at master.

$ git format-patch master..MY_BRANCH -o outgoing \
      --cover-letter

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 --annotate
$ 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
$ 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 \
      --to=ISSUE_NUMBER@debbugs.gnu.org

If need be, you may use --cover-letter --annotate to send another cover letter, e.g. for explaining what’s changed since the last revision, and these changes are necessary.