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 ms5.migadu.com with LMTPS id OCmJM/rh+mOlKAEAbAwnHQ (envelope-from ) for ; Sun, 26 Feb 2023 05:37:14 +0100 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 uK99M/rh+mN0AQAAauVa8A (envelope-from ) for ; Sun, 26 Feb 2023 05:37:14 +0100 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 4A72A16FDA for ; Sun, 26 Feb 2023 05:37:14 +0100 (CET) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1pW88q-00077Q-Kz; Sat, 25 Feb 2023 22:56:04 -0500 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 1pW88o-000770-AN for bug-guix@gnu.org; Sat, 25 Feb 2023 22:56:02 -0500 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 1pW88o-0007Ux-2K for bug-guix@gnu.org; Sat, 25 Feb 2023 22:56:02 -0500 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1pW88n-0003mg-J2 for bug-guix@gnu.org; Sat, 25 Feb 2023 22:56:01 -0500 X-Loop: help-debbugs@gnu.org Subject: bug#58813: [PATCH] doc: Document how to use Patman for patches submission. References: <87r0yuq615.fsf@gmail.com> In-Reply-To: <87r0yuq615.fsf@gmail.com> Resent-From: Maxim Cournoyer Original-Sender: "Debbugs-submit" Resent-CC: bug-guix@gnu.org Resent-Date: Sun, 26 Feb 2023 03:56:01 +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.167738373814517 (code B ref 58813); Sun, 26 Feb 2023 03:56:01 +0000 Received: (at 58813) by debbugs.gnu.org; 26 Feb 2023 03:55:38 +0000 Received: from localhost ([127.0.0.1]:42058 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pW88P-0003m3-Ux for submit@debbugs.gnu.org; Sat, 25 Feb 2023 22:55:38 -0500 Received: from mail-qt1-f182.google.com ([209.85.160.182]:36832) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pW88N-0003ln-3p for 58813@debbugs.gnu.org; Sat, 25 Feb 2023 22:55:35 -0500 Received: by mail-qt1-f182.google.com with SMTP id l13so3539354qtv.3 for <58813@debbugs.gnu.org>; Sat, 25 Feb 2023 19:55:35 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:from:to:cc:subject:date:message-id:reply-to; bh=1gUfnvvnbmdlYW3f/WlStTGuQbsvHdpDk5Mj407OUog=; b=mem+rYpqjw9o4jbXp0s1soBPgdi8h1GCu50Au6u7KYL8OkwmA49B7MVDt3ZUn0HLKg fxV/sjHFGKbee1iKdE7MympQdFVDlX6Qtohnz0NiirrmAqBuDA7bNDipM9Z+UPvz+6Hf g4iE/soPcJBGlALNOBQOvJlbiie1XCaNHFL1lqkR928q4C5rc1+4I3IbJdE7i/utihDR v18VZIbWS8e70VuTdbY8HB7VZUIgvYM1gGb9lX+O9sSfUv48zIwYDeoihQCouzre5zwT jyrnjXgwTWnCxf/z6GpzfX3Kh28NUR1lEZpjPyTfABvZINbMzSDjHjpmgpefUaaYZsxG GNnw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=1gUfnvvnbmdlYW3f/WlStTGuQbsvHdpDk5Mj407OUog=; b=z+GJPlFZ5rVavDna0IlbHaAzjkElAo17a8IL70aqK99RbonusgVc68cZ5HZNQOYGMg eAg/ZC6I3NjXKmQ5vhc8I/r2OTSrQOQ/HOyUS4zaYnZc3rX/KsfFwV6HzQzT3T8Osjra Jh7YS+Ch7u/yBIOQyWw7YXRwFNU02Gec2f+tG1ALp7Ja1Ev35g07XXN3GJkpFMK+73Lh 9gwT8+ubxRlYHB+MSkmmNV5AEEJff4qgXNts8biKKKXlC87b+qNWcqDySakhRWt+4oDN 5lABo1WFVptcob5n4tR7Vsmywil1KMIA11OrZV/IpJfvaX+OyfZT6G7YsQBNjE+7WATy MI3w== X-Gm-Message-State: AO0yUKU2soyIeNGtYBYlO1tIRpHw46YX9esTj8kRh3WiOwUpMMa4vju+ e4suGk5bmRmyYeQCrw8riVWoHPAO8g20bNZG X-Google-Smtp-Source: AK7set/lq2/8Fs8teFbRUh6VwmcAd+HFm7GzsnTapxZG5JxILES/mWWB/2lWXaf+tWLjrMwV73wWww== X-Received: by 2002:ac8:59d5:0:b0:3bf:bbaf:5c82 with SMTP id f21-20020ac859d5000000b003bfbbaf5c82mr9074470qtf.21.1677383729104; Sat, 25 Feb 2023 19:55:29 -0800 (PST) Received: from localhost.localdomain (dsl-141-27.b2b2c.ca. [66.158.141.27]) by smtp.gmail.com with ESMTPSA id z134-20020a37658c000000b007423c011937sm2354511qkb.91.2023.02.25.19.55.27 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 25 Feb 2023 19:55:28 -0800 (PST) From: Maxim Cournoyer Date: Sat, 25 Feb 2023 22:55:14 -0500 Message-Id: <20230226035515.16214-1-maxim.cournoyer@gmail.com> X-Mailer: git-send-email 2.39.1 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=1677386234; a=rsa-sha256; cv=none; b=i9GB27YObS9m7lUcgzTnnt+O2dUtrOjiFdt4s3OA93hKkh5yswXAq5FgK1JwGTegsF9pjN 0lO90z3NyJBoRuJHuidf0etL4bz2DZIHzVQyvZYw0LWTCEQTzH3cT5f7VhdXMJwmPUySPV efGFjgC/LfnxNuRoVYbVzzbsH131lX8CON+xVmbf/gXBmjTflI9dIGZIMg1ArVnIoBIg3A 10cTj3Mx1PhLTacAJA3vzEIM1nyNiB+7rCBKV4R+ZAh9WaHJyqhyFlcGtHoBl4bqw4acxT iBC7PrFDuUJQD8sbjkEyIOL4rLi/5TFtxosZ2mJHNfSz5s/lX5UM94y0aNLIQw== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=gmail.com header.s=20210112 header.b=mem+rYpq; 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"; dmarc=fail reason="SPF not aligned (relaxed)" header.from=gmail.com (policy=none) ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1677386234; 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=1gUfnvvnbmdlYW3f/WlStTGuQbsvHdpDk5Mj407OUog=; b=KmLbLlV4vaGJXX1KIkGHQ5jsYBE1YL2puAvp9aIbjzAuImbSK/ynUaUrVts1mcABGnp42Q fzwf84o6YggTwslgeoKT/jOPpEru7MFPtYyYoRCNM44+StLOLkgiLtXfo/DzxFxHyx85yo vaKSH9z1aEUpcyYo7KPHXpdIh1MIIEYAf48i9H/kBTEH+6nOkCSLkWjBlJuZtKjNpR+bWe KRfTryjIDfhnZiDny7d1LlTz2aSRsG+e7rguNXj4mEM8BELCBbtv344+ItCtRDRURDhCKY yS9l6qavNHTXDkV5tTzbE7QDszlH4X/SQhuKLgB5Bpy5K8ffqGodojP8NkniSw== X-Migadu-Queue-Id: 4A72A16FDA X-Migadu-Scanner: scn1.migadu.com Authentication-Results: aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=gmail.com header.s=20210112 header.b=mem+rYpq; 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"; dmarc=fail reason="SPF not aligned (relaxed)" header.from=gmail.com (policy=none) X-Migadu-Spam-Score: -0.58 X-Spam-Score: -0.58 X-TUID: sVYxq3mB1pmU Fixes . * doc/contributing.texi (Sending a Patch Series): Mention Patman. Adjust the examples to no longer showcase broken command substitutions. Add a section about how to use Patman, with examples. --- doc/contributing.texi | 119 ++++++++++++++++++++++++++++++++++++++---- doc/guix.texi | 2 +- 2 files changed, 110 insertions(+), 11 deletions(-) diff --git a/doc/contributing.texi b/doc/contributing.texi index c436bc4a31..2a12dffefe 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -1416,12 +1416,19 @@ git config --local sendemail.thread no @cindex @code{git format-patch} @unnumberedsubsubsec Single Patches -@anchor{Single Patches} -The @command{git send-email} command is the best way to send both single -patches and patch series (@pxref{Multiple Patches}) to the Guix mailing -list. Sending patches as email attachments may make them difficult to -review in some mail clients, and @command{git diff} does not store commit -metadata. +@cindex patman patch manager +@cindex patch management, via patman +@anchor{Single Patches} The @command{git send-email} command is the best +way to send both single patches and patch series (@pxref{Multiple +Patches}) to the Guix mailing list. Sending patches as email +attachments may make them difficult to review in some mail clients, and +@command{git diff} does not store commit metadata. If you want +something a bit higher level than @command{git send-email} to organize +your patch submissions and take care of its various options for you, you +may want to try the @command{patman} command, from the eponymous +package. Patman's help can be accessed via @samp{patman -H} or as an +Info manual after installing the @code{u-boot-documentation} package +(@pxref{Patman patch manager,,,u-boot,The U-Boot Documentation}). @quotation Note The @command{git send-email} command is provided by the @code{send-email} @@ -1521,7 +1528,7 @@ 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 ...) + --cc=team-member1@@example.org --cc=team-member2@@example.org ... $ rm outgoing/0000-cover-letter.patch # we don't want to resend it! @end example @@ -1535,7 +1542,7 @@ 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 ...) + --cc=team-member1@@example.org --cc=team-member2@@example.org ... $ rm -rf outgoing # we don't need these anymore @end example @@ -1578,18 +1585,110 @@ 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 +$ ./etc/teams.scm cc mentors @end example +then note the @var{output} of the script. + +@example +$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org @var{output} *.patch +@end example + +Taking care to manually splice the @var{output} of the +@file{etc/teams.scm} script into the command. + The appropriate team or teams can also be inferred from the modified files. For instance, if you want to send the two latest commits of the 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 @var{output} *.patch @end example +@cindex patman, usage example +As manually stitching the output of the @file{etc/teams.scm} script in +the @command{git send-email} command can get tedious; you may prefer to +use Patman to automate this for you. Its necessary basic configuration +is already found at the root of the Guix repository, in the +@file{.patman} file. Another useful bit to have is a default +destination for the @command{git send-email} command. You can specify +it in your repository-local Guix @file{.git/config} file with: + +@example +[sendemail] + to = guix-patches@@gnu.org +@end example + +To send a long series to Debbugs, the patches can be written to the +current directory with: + +@example +patman -n +@end example + +The first patch should then be sent using @samp{git send-email +0000-cover-letter.patch}, as explained earlier (@pxref{Multiple +Patches}). + +After Debbugs has issued a unique bug email in reply to that initial +patch submission, e.g. @email{NNNNN@@debbugs.gnu.org}, you can save this +information into the top commit of your patch series (it doesn't matter +which, but it's more convenient to amend it later when it's at the top) +like so, via the Patman-specific @code{Series-to} git message tag: + +@example +gnu: Add foo. + +* gnu/packages/dummy.scm: Add foo. + +Series-to: NNNNN@@debbugs.gnu.org +@end example + +You can then send your series to that address with the right people +automatically added in CC by simply issuing: + +@example +patman +@end example + +After addressing the first round of review comments, you can annotate a +v2 patch series by adding these Patman-specific git message tags: + +@example +gnu: Add foo. + +* gnu/packages/dummy.scm: Add foo. + +Series-to: NNNNN@@debbugs.gnu.org +Series-version: 2 +Series-changes: 2 +- Factorized X into Y and Z + +@end example + +The @command{patman} command will then take care to automate the right +@code{git send-email} command and produce patch annotations useful for +the reviewers. + +After the review is complete, if you are the one merging your own +changes, you should take care to strip any Patman git message tags. +This can be done by writing the patches to the current directory with: + +@example +patman -n +@end example + +and then applying them to the main branch with: + +@example +git am *.patch +@end example + +For more information, run @samp{patman -H} or read its info manual, +which can be installed with the @code{u-boot-documentation} package +(@pxref{Patman patch manager,,,u-boot,The U-Boot Documentation}). + @node Tracking Bugs and Patches @section Tracking Bugs and Patches diff --git a/doc/guix.texi b/doc/guix.texi index a7ef00f421..5a4900d7cf 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@* base-commit: 9a2cf9ef0a9ece9aa0dcb24a31fe0c313d06988f -- 2.39.1