From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp11.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms9.migadu.com with LMTPS id LVfFC9/pRWSqVgAASxT56A (envelope-from ) for ; Mon, 24 Apr 2023 04:30:55 +0200 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp11.migadu.com with LMTPS id YEwCC9/pRWRRNgAA9RJhRA (envelope-from ) for ; Mon, 24 Apr 2023 04:30:55 +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 A0C50F4C7 for ; Mon, 24 Apr 2023 04:30:53 +0200 (CEST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1pqlxz-0000Zw-Ky; Sun, 23 Apr 2023 22:30:11 -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 1pqlxt-0000ZA-76 for bug-guix@gnu.org; Sun, 23 Apr 2023 22:30:06 -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 1pqlxs-00016I-UP for bug-guix@gnu.org; Sun, 23 Apr 2023 22:30:04 -0400 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1pqlxs-0002Pe-Pr for bug-guix@gnu.org; Sun, 23 Apr 2023 22:30:04 -0400 X-Loop: help-debbugs@gnu.org Subject: bug#58813: [PATCH v2 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: Mon, 24 Apr 2023 02:30: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.16823033979195 (code B ref 58813); Mon, 24 Apr 2023 02:30:04 +0000 Received: (at 58813) by debbugs.gnu.org; 24 Apr 2023 02:29:57 +0000 Received: from localhost ([127.0.0.1]:47262 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pqlxk-0002OD-Nm for submit@debbugs.gnu.org; Sun, 23 Apr 2023 22:29:57 -0400 Received: from mail-qv1-f43.google.com ([209.85.219.43]:45170) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pqlxY-0002My-Vu for 58813@debbugs.gnu.org; Sun, 23 Apr 2023 22:29:45 -0400 Received: by mail-qv1-f43.google.com with SMTP id 6a1803df08f44-5ef50358a7aso17582826d6.2 for <58813@debbugs.gnu.org>; Sun, 23 Apr 2023 19:29:44 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20221208; t=1682303379; x=1684895379; 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=p24zlu90GN394VEiyJM5NYz0RdfImyXF7Zs5jWkYeuY=; b=FQqszb9MtfxDr1oIdZPEzF+PTckItIZmAA5WZv7R5N1V6vujJzXugbto1Bichg5eYl oG+loWd0DDRix3q08i48NamV/GNUxrIGF98PzGxY9tKwkGvBjlCEkX6845f4+ETFLdGV XyemKkOkRux4cYB9czYYiIkOJOG2VejKktij7l1UUtEojfvehmqfW3r+KhFtI8nv5DIg u2zvIVIWMHoTCjTbKM4yrpm9G4Er2D44nmJSLBsPEHIEZ4/1BYbXuiIH7WWOqRPkFySw ss6TGo0l779c4zWkt6NiM7XpBypz/tvsiYRR4zng7ODcW0FUsgdLC+EKhmpnkqSgQNh2 /KfQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1682303379; x=1684895379; 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=p24zlu90GN394VEiyJM5NYz0RdfImyXF7Zs5jWkYeuY=; b=UTq1+w/L8w6M7IqoLg5UyMrI9KXnlDrjino9frVLiVclowc2tbialwIz5dB103DJDK XRrqvmt+TpZ3PACeaYzNLO8VKGe5jDQUacrM4PMfOUliuNIK6X2GTuA+XH8VDshku9K/ 1TQiJXcYxmaVr1f/CyGpik91SEdd1Jw4edDOMci8L6gb4HaPJxLqwRp9sk3odP0LfQzV 3jIwBoFLqeQoTnAzZg5IFQgNtCdUpZQlqhfHpD5z2U6BCF/8R9P1fGNx9ev3P2WEsbuA 7KWh7l1qGZQ9xetWKRDz9pMU/3CWSbHiDW1auoTLWADcQHNJkRff8wnLqj4c3AcdV9x1 9Zog== X-Gm-Message-State: AAQBX9d53ioLo8MjFArl7b8pleB1SDEpzEg+AcR5eSmh6v7eQJAZyx+Y JA2tokfxawJJ8bSl7DRm1eUoNSNaqh0= X-Google-Smtp-Source: AKy350aCkSnrd8ydtvQC3L+zPzNfmZst/xzXbWsIx/UW8/rnbt52Ojw33NgHOyiv4C+hyNMgm7LPBQ== X-Received: by 2002:a05:6214:4111:b0:5ef:519:b27 with SMTP id kc17-20020a056214411100b005ef05190b27mr20647807qvb.35.1682303379248; Sun, 23 Apr 2023 19:29:39 -0700 (PDT) Received: from localhost.localdomain (dsl-141-20.b2b2c.ca. [66.158.141.20]) by smtp.gmail.com with ESMTPSA id a4-20020a0ce384000000b005ef658e65b8sm2986472qvl.121.2023.04.23.19.29.38 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 23 Apr 2023 19:29:38 -0700 (PDT) From: Maxim Cournoyer Date: Sun, 23 Apr 2023 22:29:27 -0400 Message-Id: <8f46ecccc4343c24e9fc0d8b9c8cf5504ef2601d.1682303142.git.maxim.cournoyer@gmail.com> X-Mailer: git-send-email 2.39.2 In-Reply-To: <5b9af4fa77a89c6a4b169dc464f414b1a4166d60.camel@gmail.com> References: <5b9af4fa77a89c6a4b169dc464f414b1a4166d60.camel@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-Flow: FLOW_IN X-Migadu-Country: US ARC-Seal: i=1; s=key1; d=yhetil.org; t=1682303453; a=rsa-sha256; cv=none; b=EtkacTDuEZxwrLsbL6wXkc3sAHmA8+IiJ6/SPYl5WlmSj53c6kZ2m43n45UJJpeInTeLus +Qh983ctJe4gqts79I8fn7olxSyrb8Dij1lhORJ7DGxGPE2mtApMsAlX7WwzvdMlsZzd4c iJUPfz6qKvnKd2HvzHcBJpDq8mm1briD3I8M2hXOJtT0vfA9lKzwtpt8nK2H/YF7FnJc9w m9mOjHeVoIV8Ss5V/8tJremRpt/XIDKuF9P1v2wI4FH2JTW45u0lpXQnrNjOcoO9ImwKQw 5aJlFHI4kmj+xCjvaxr4vEOCd/jtCxVQTWkWrX+ga9ZP23BPlECAxoJ2sTCpjw== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=gmail.com header.s=20221208 header.b=FQqszb9M; 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=1682303453; 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=p24zlu90GN394VEiyJM5NYz0RdfImyXF7Zs5jWkYeuY=; b=Vk4SKKQHq2BIuOUXv9P5ffv7JexIleeTGCMDtuWO4qXDhawdBQtfkWiVJm9VwWPJ0tjWGm YOXfZpTMZyoL8XLSYBecX9IwdNLdR2gx6tjUsiy7/L6m5QQ1OIro8cQQ5UKSl3RY7ms4nC Tql7pWETX1scv3Fiyhgxybicymp9cYnfpppwQu2GVPXuAKWyWcnyvQ2viGL28Dey3n6tNr Uuvb3SzYyF+904YXsuBeCITW7TqcOi/z5OprTF/hFZnHVRQurWtjiZWY3AA3jBWXjMOMtn AtdfJ+cItAUHnX6ZoRFnhu3q7JbYoPOYFKgLX8UO5rn0YZ4O6oZhBUSDYoPZjw== X-Migadu-Scanner: scn1.migadu.com Authentication-Results: aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=gmail.com header.s=20221208 header.b=FQqszb9M; 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-Migadu-Spam-Score: 7.29 X-Spam-Score: 7.29 X-Migadu-Queue-Id: A0C50F4C7 X-TUID: YDXJ0qccemrY Fixes . 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, which is also automatic. * doc/contributing.texi (Configuring Git): Streamline section, now automated via Automake. (Sending a Patch Series): Do not specify options configured as default by the above. Prefer long option names, for readability. (Teams): Rewrite the examples to use --header-cmd. (Commit Access): Refer to the Configuring Git section instead of detailing manual steps. --- doc/contributing.texi | 104 ++++++++++++++---------------------------- doc/guix.texi | 2 +- 2 files changed, 36 insertions(+), 70 deletions(-) diff --git a/doc/contributing.texi b/doc/contributing.texi index 73d1cd2648..b13531c5cc 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -1395,28 +1395,8 @@ 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: - -@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 @@ 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 +1435,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 +1471,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 +1505,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 +1517,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 +1526,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 +1559,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 +1569,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 +1804,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