diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/contributing.texi | 104 | ||||
| -rw-r--r-- | doc/guix.texi | 2 |
2 files changed, 36 insertions, 70 deletions
diff --git a/doc/contributing.texi b/doc/contributing.texi index 2a30b5055a..1d7499cfac 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -1395,28 +1395,8 @@ different name or email just for commits in this repository, you can use @command{git config --local}, or edit @file{.git/config} in the repository instead of @file{~/.gitconfig}. -We provide some default settings in @file{etc/git/gitconfig} which -modify how patches are generated, making them easier to read and apply. -These settings can be applied by manually copying them to -@file{.git/config} in your checkout, or by telling Git to include the -whole file: - -@example -git config --local include.path ../etc/git/gitconfig -@end example - -From then on, any changes to @file{etc/git/gitconfig} would -automatically take effect. - -Since the first patch in a series must be sent separately -(@pxref{Sending a Patch Series}), it can also be helpful to tell -@command{git format-patch} to handle the e-mail threading instead of -@command{git send-email}: - -@example -git config --local format.thread shallow -git config --local sendemail.thread no -@end example +Other important Git configuration will automatically be configured when +building the project (@pxref{Building from Git}). @node Sending a Patch Series @subsection Sending a Patch Series @@ -1439,10 +1419,12 @@ output of the @code{git} package, i.e. @code{git:send-email}. 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: +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 -1 -a --base=auto --to=guix-patches@@gnu.org +$ git send-email --annotate -1 @end example @quotation Tip @@ -1453,31 +1435,26 @@ other than the @code{master} branch of @url{https://git.savannah.gnu.org/cgit/guix.git}. @example -git send-email -1 -a --base=auto \ - --subject-prefix='PATCH core-updates' \ - --to=guix-patches@@gnu.org +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{-a} flag (which is short for @option{--annotate}). - -The @option{--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. +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 -a} 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}. +@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 -a -$ git send-email -1 -a --base=auto -v@var{REVISION} \ - --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org +$ git commit --amend +$ git send-email --annotate -v@var{REVISION} \ + --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org -1 @end example @quotation Note @@ -1494,14 +1471,14 @@ reply to incoming bugs and patches, which contains the bug number. @unnumberedsubsubsec Notifying Teams @anchor{Notifying Teams} @cindex teams -The @file{etc/teams.scm} script may be used to notify all those who -may be interested in your patch of its existence (@pxref{Teams}). -Use @command{etc/teams.scm list-teams} to display all the teams, -decide which team(s) your patch relates to, and use -@command{etc/teams.scm cc} to output various @command{git send-email} -flags which will notify the appropriate team members, or use -@command{etc/teams.scm cc-members} to detect the appropriate teams -automatically. +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, see @xref{Teams}. @unnumberedsubsubsec Multiple Patches @anchor{Multiple Patches} @@ -1528,9 +1505,7 @@ We can now send @emph{just} the cover letter to the that we can send the rest of the patches to. @example -$ git send-email outgoing/0000-cover-letter.patch -a \ - --to=guix-patches@@gnu.org \ - $(etc/teams.scm cc-members ...) +$ git send-email outgoing/0000-cover-letter.patch --annotate $ rm outgoing/0000-cover-letter.patch # we don't want to resend it! @end example @@ -1542,9 +1517,7 @@ 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 \ - $(etc/teams.scm cc-members ...) +$ git send-email outgoing/*.patch --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org $ rm -rf outgoing # we don't need these anymore @end example @@ -1553,14 +1526,13 @@ to send an amended patch series, since an issue already exists for the patchset. @example -$ git send-email -@var{NUMBER_COMMITS} \ - -v@var{REVISION} --base=auto \ +$ 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 -a} to send another cover -letter, e.g. for explaining what's changed since the last revision, and -these changes are necessary. +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 these changes are necessary. @node Teams @subsection Teams @@ -1587,7 +1559,8 @@ You can run the following command to have the @code{Mentors} team put in CC of a patch series: @example -$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org $(./etc/teams.scm cc mentors) *.patch +$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org \ + --header-cmd='etc/teams.scm cc-mentors-header-cmd' *.patch @end example The appropriate team or teams can also be inferred from the modified @@ -1596,7 +1569,7 @@ current Git repository to review, you can run: @example $ guix shell -D guix -[env]$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org $(./etc/teams.scm cc-members HEAD~2 HEAD) *.patch +[env]$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org -2 @end example @node Tracking Bugs and Patches @@ -1831,16 +1804,9 @@ To check that commits are signed with correct key, use: make authenticate @end example -You can prevent yourself from accidentally pushing unsigned or signed -with the wrong key commits to Savannah by using the pre-push Git hook -located at @file{etc/git/pre-push}: - -@example -cp etc/git/pre-push .git/hooks/pre-push -@end example - -It additionally calls @code{make check-channel-news} to be sure -@file{news.scm} file is correct. +To avoid accidentally pushing unsigned or signed with the wrong key +commits to Savannah, make sure to configure Git according to +@xref{Configuring Git}. @subsection Commit Policy diff --git a/doc/guix.texi b/doc/guix.texi index 46e7fd3908..7af2a85499 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -49,7 +49,7 @@ Copyright @copyright{} 2017 humanitiesNerd@* Copyright @copyright{} 2017, 2021 Christine Lemmer-Webber@* Copyright @copyright{} 2017, 2018, 2019, 2020, 2021, 2022 Marius Bakke@* Copyright @copyright{} 2017, 2019, 2020, 2022 Hartmut Goebel@* -Copyright @copyright{} 2017, 2019, 2020, 2021, 2022 Maxim Cournoyer@* +Copyright @copyright{} 2017, 2019, 2020, 2021, 2022, 2023 Maxim Cournoyer@* Copyright @copyright{} 2017–2022 Tobias Geerinckx-Rice@* Copyright @copyright{} 2017 George Clemmer@* Copyright @copyright{} 2017 Andy Wingo@* |