From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp12.migadu.com ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms9.migadu.com with LMTPS id WK43EkxXRWSIGAEASxT56A (envelope-from ) for ; Sun, 23 Apr 2023 18:05:32 +0200 Received: from aspmx1.migadu.com ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp12.migadu.com with LMTPS id OMj8EUxXRWRyzQAAauVa8A (envelope-from ) for ; Sun, 23 Apr 2023 18:05:32 +0200 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id DD0AD3E7C3 for ; Sun, 23 Apr 2023 18:05:31 +0200 (CEST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1pqcDJ-00062w-ST; Sun, 23 Apr 2023 12:05:21 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pqcD3-000620-Jk for bug-guix@gnu.org; Sun, 23 Apr 2023 12:05:07 -0400 Received: from debbugs.gnu.org ([209.51.188.43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1pqcD2-0002MT-TA for bug-guix@gnu.org; Sun, 23 Apr 2023 12:05:04 -0400 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1pqcD2-0004id-OF for bug-guix@gnu.org; Sun, 23 Apr 2023 12:05:04 -0400 X-Loop: help-debbugs@gnu.org Subject: bug#58813: [PATCH 5/5] doc: Simplify contributing section by automating git configuration. Resent-From: Maxim Cournoyer Original-Sender: "Debbugs-submit" Resent-CC: bug-guix@gnu.org Resent-Date: Sun, 23 Apr 2023 16:05:04 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 58813 X-GNU-PR-Package: guix X-GNU-PR-Keywords: To: 58813@debbugs.gnu.org Cc: ludo@gnu.org, liliana.prikler@gmail.com, Maxim Cournoyer , zimon.toutoune@gmail.com Received: via spool by 58813-submit@debbugs.gnu.org id=B58813.168226588718068 (code B ref 58813); Sun, 23 Apr 2023 16:05:04 +0000 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 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-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-guix@gnu.org List-Id: Bug reports for GNU Guix List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-guix-bounces+larch=yhetil.org@gnu.org Sender: bug-guix-bounces+larch=yhetil.org@gnu.org X-Migadu-Country: US X-Migadu-Flow: FLOW_IN ARC-Seal: i=1; s=key1; d=yhetil.org; t=1682265932; a=rsa-sha256; cv=none; b=cH1n3pqo+krnYdgsyKWGaRJu0mUeUXKdcy1pIHeacO4vGFAByamUnP51NENqJknMQFdu63 SpvCRTt1sEEPpZ1exwwqzpJQlUxaorSMUl4IGsm9gi4dwmKtpfmO4s8G2HDZoBfOtwE5AZ 8p60mRmD/Vs98noQfWCuszi6Mi5LwiiQ1zC7QU3t+M2xECMjhOi/nMM5/3ILEkjQPePPWQ pcNKUI3zZfN4Bwo6E8qlci8HERoTQxfNKUT40YSHBOX+AmUA8kFIcLujJXXhYxjVCzw7nq 0PwNBLGHu6Mbwkthbs6zdAIa2wKEB2AvEtZv6v/Lp/3StEKCGlIjKfHezabEHw== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=gmail.com header.s=20221208 header.b=mF6jOamx; dmarc=fail reason="SPF not aligned (relaxed)" header.from=gmail.com (policy=none); spf=pass (aspmx1.migadu.com: domain of "bug-guix-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="bug-guix-bounces+larch=yhetil.org@gnu.org" ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1682265932; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding:resent-cc: resent-from:resent-sender:resent-message-id:in-reply-to:in-reply-to: references:references:list-id:list-help:list-unsubscribe: list-subscribe:list-post:dkim-signature; bh=Ib1xfOp9MuqQvZDLhRJP8AChmjvj3X995tTjsXJcjTY=; b=G8L5YICmV89L1XF+zj20ascelsPy2QaHGQJJILoUec5e8M9y4idQjbF8wN3vW2jV76zxa1 G545QC96qpTXZtGWcp8iFvDcNbiX3Zj3AvXmtTtUENxXkQ+X14QgF7ZMg7RTP+76n+IBfu zy67TnfNMo8KtsWURw5vKvkDX30Ci87e1QSFp5JYPctbkVa2+zTsNFiMJpqDLBUiNhafU6 g5ywyaiypP2ynLrV1u3YILLbpxpi0n3uWF3DufrJnCv7TkNd3LxwfpPcf22D7mHngwDvbn pq31kud2KGmQfNrwveKih61l+LSu+85EssFOF+9iTyosh1QOld4G2JbnuIr+Qg== X-Migadu-Spam-Score: -1.71 X-Spam-Score: -1.71 X-Migadu-Queue-Id: DD0AD3E7C3 X-Migadu-Scanner: scn0.migadu.com Authentication-Results: aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=gmail.com header.s=20221208 header.b=mF6jOamx; dmarc=fail reason="SPF not aligned (relaxed)" header.from=gmail.com (policy=none); spf=pass (aspmx1.migadu.com: domain of "bug-guix-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="bug-guix-bounces+larch=yhetil.org@gnu.org" X-TUID: nMFRt6HWzlNM 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