From debbugs-submit-bounces@debbugs.gnu.org Sun Apr 23 12:04:47 2023 Received: (at 58813) by debbugs.gnu.org; 23 Apr 2023 16:04:47 +0000 Received: from localhost ([127.0.0.1]:46820 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pqcCk-0004hH-Nu for submit@debbugs.gnu.org; Sun, 23 Apr 2023 12:04:47 -0400 Received: from mail-qt1-f175.google.com ([209.85.160.175]:50633) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pqcCa-0004g1-KJ for 58813@debbugs.gnu.org; Sun, 23 Apr 2023 12:04:37 -0400 Received: by mail-qt1-f175.google.com with SMTP id d75a77b69052e-3ef588dcf7aso33405751cf.1 for <58813@debbugs.gnu.org>; Sun, 23 Apr 2023 09:04:36 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20221208; t=1682265871; x=1684857871; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=Ib1xfOp9MuqQvZDLhRJP8AChmjvj3X995tTjsXJcjTY=; b=mF6jOamxznfIgBb0qy7IvxX59gWMrv6vhw0UxFU/4x0hUvSX820ymQnEnjqn0yfGRj bYRGHIGyzj1r6ZokoUcDYUVNCHgaA4hfPyOgFQrEmoJgezYDrYyE3ILAznlr9ZCC7Mah tr3C/Sfv/KOEUR7eAj56plqA+ZNSFWReUzDBCG4RX7Re7np1vyZhkAZKQnZR7dJh5fSy el9knIVvMEb/qnLz8rKH/pJ7PabJlZOz8M9aB31mTMxG5gRW0RwAKCVibPhsmWSPKvAe 5RWkX+qsluxxGuguvQD4YQk7G/ItOd6aZwcWx7HZrQUl72bRZVCbOUkLdbv9lLnp7xgZ A4UQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1682265871; x=1684857871; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=Ib1xfOp9MuqQvZDLhRJP8AChmjvj3X995tTjsXJcjTY=; b=E8B68YvOD16z2IfcC/lvq54uMiHyln+q3sPyY+XndGqgwVq8fqj/wBtkX5F90H770i SQuxNxkgU5vn0Qw2aJLwDn5SFSMuPnRQBIMBnHt4LMp05UEEWrAymYibtL4IV36fE7yX Z0ht2xSxLVyDYPlClO2wAOKdzc20Wx/e5D/dBoHMBhg6LRswDygufTuDP9v4IBL+ozoO FrTeyx/seyjWbCVDkpjtFy1np4639kScrVNuYlF+2duY2q9srHHk0IAcInNp60CBnIWw R1G2h+ySQ+3TnsNBbgB1rskX6+dVzG41BNL+9n7uf6DnbqYRaaYFiez7gKmrlrFyscR1 gBKQ== X-Gm-Message-State: AAQBX9drENErp7A7YzTGgKctEn6d/GUhFvwa469Dlqh8K1Ycb6dCY/As ew2wlagA4HtVzrwPozSbUkPfMAdck4a+LQ== X-Google-Smtp-Source: AKy350aP4jeIXQGcZDRti2bjrZ9qf7Z0TXtrkdFYU1uEETD5yMsWjWDtqCY68QSYvI4gWrwFy6GmKA== X-Received: by 2002:a05:622a:1301:b0:3ef:68ea:e253 with SMTP id v1-20020a05622a130100b003ef68eae253mr7470494qtk.19.1682265870934; Sun, 23 Apr 2023 09:04:30 -0700 (PDT) Received: from localhost.localdomain (dsl-141-20.b2b2c.ca. [66.158.141.20]) by smtp.gmail.com with ESMTPSA id d13-20020a05622a15cd00b003ef48392649sm2957469qty.4.2023.04.23.09.04.30 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 23 Apr 2023 09:04:30 -0700 (PDT) From: Maxim Cournoyer To: 58813@debbugs.gnu.org Subject: [PATCH 5/5] doc: Simplify contributing section by automating git configuration. Date: Sun, 23 Apr 2023 12:04:15 -0400 Message-Id: X-Mailer: git-send-email 2.39.2 In-Reply-To: <878rg4snrf.fsf@gmail.com> References: <878rg4snrf.fsf@gmail.com> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 58813 Cc: ludo@gnu.org, liliana.prikler@gmail.com, Maxim Cournoyer , zimon.toutoune@gmail.com X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) Fixes . Instead of documenting all the fine details of Git configuration, invite users to configure their checkout with 'etc/teams configure-git'. No longer suggests to splice the output of etc/teams.scm commands into the 'git send-email' command line; this is now transparently handled by the Git configuration. * doc/contributing.texi (Configuring Git): Move configuration setup to 'etc/teams.scm configure-git'. (Sending a Patch Series): Do not specify options configured as default by the above. Prefer long option names, for explicitness. (Teams): Rewrite the examples to use --header-cmd. (Commit Access): Refer to the Configuring Git section instead of detailing manual steps. --- doc/contributing.texi | 102 +++++++++++++++--------------------------- doc/guix.texi | 2 +- 2 files changed, 37 insertions(+), 67 deletions(-) diff --git a/doc/contributing.texi b/doc/contributing.texi index 73d1cd2648..fb72238487 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -1395,27 +1395,11 @@ Configuring Git 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: +To configure automatically your local Git checkout to use the +recommended settings and hooks, run the following command once: @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 +etc/teams.scm configure-git @end example @node Sending a Patch Series @@ -1439,10 +1423,12 @@ Sending a Patch Series 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 +1439,26 @@ Sending a Patch Series @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 +1475,14 @@ Sending a Patch Series @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 +1509,7 @@ Sending a Patch Series 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 +1521,7 @@ Sending a Patch Series 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 +1530,13 @@ Sending a Patch Series 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 +1563,8 @@ Teams 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 +1573,7 @@ Teams @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 +1808,9 @@ Commit Access 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 9997aeb86e..e5f6c7e831 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -49,7 +49,7 @@ 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@* -- 2.39.2