From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp10.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 25J2E7QhB2QzHgAASxT56A (envelope-from ) for ; Tue, 07 Mar 2023 12:36:20 +0100 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp10.migadu.com with LMTPS id aIKzEbQhB2RNPAAAG6o9tA (envelope-from ) for ; Tue, 07 Mar 2023 12:36:20 +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 CA13117B93 for ; Tue, 7 Mar 2023 12:36:19 +0100 (CET) Authentication-Results: aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=gmail.com header.s=20210112 header.b=cDdiAqCu; 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=1678188979; 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=l8jFFFH3vagAVYZSJp5vTEh6HYZLfa/hKI7ogF/IZlU=; b=Cw1D75VhhGraoRzZu+l8Mifft76WsBcZg7zDhAog4oZzkx7JFeWbsqlcmUnV3tOej+mEOa f6ksJg+fzZWvCna4iN1Zca8hqb/bWn9osuyY/OP5d0jrS+vqAqlWPZNNCNlBjUUX5Xlj2j Wp51B+bMYOyMaZMLFOF8HzeqCvtJUwfWXAElswrwPScRXY09mTxj4QmuYA+w3Z1zzll9gC nVaLFUmyZquAlqVKKZXR6sTJEMhbwsOSPFHphn2oo0+XZrmlCsXD+WI7LKI41TKQhua6pG mICh8rzjV0pzh3cuRpm7JiZAKGYA3GL8VyCini2UI1NAfAKzIIi9Md7QuzbxWg== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1678188979; a=rsa-sha256; cv=none; b=Mt8Kt0h48IgAYU86Dg5Z6F29dUPshGIQX7uesu/7xpsu9U3f9xXlqcPK1jOsPC6l7Oi9TZ MePAhlx6Tmw+Z8FhGPKz9QgzvB1sRJIYhNlT6ZFWPylx9TW3IAuNw7CC8yiXJByviDVVfS lSzRFBJQhjNkwv5XASfMMCRMftp6oJ8fFk5Lz0nd4ouDqJxiXoYSWTAQKBhsNGYx8FsMiy UT/OpGm767Jgn6Lu8eXmZhHD+2MsVCa5ZvrH+k3X4YWCOekLcoie0Pp13ubqlzxFAE6fqk CePRatZHkuArDBFN2XlxjvRxU7uW/nWOOR8J59IEN8mnjAEhKGfitOI0GVAu6g== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=gmail.com header.s=20210112 header.b=cDdiAqCu; 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) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1pZVbw-0007o5-1j; Tue, 07 Mar 2023 06:36: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 1pZVbv-0007nG-1E for bug-guix@gnu.org; Tue, 07 Mar 2023 06:36:03 -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 1pZVbu-00073p-PB for bug-guix@gnu.org; Tue, 07 Mar 2023 06:36:02 -0500 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1pZVbu-0006QU-GW for bug-guix@gnu.org; Tue, 07 Mar 2023 06:36:02 -0500 X-Loop: help-debbugs@gnu.org Subject: bug#58813: [PATCH v2] doc: Document how to use Patman for patches submission. References: <87r0yuq615.fsf@gmail.com> In-Reply-To: <87r0yuq615.fsf@gmail.com> Resent-From: Simon Tournier Original-Sender: "Debbugs-submit" Resent-CC: bug-guix@gnu.org Resent-Date: Tue, 07 Mar 2023 11:36:02 +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@gmail.com Received: via spool by 58813-submit@debbugs.gnu.org id=B58813.167818893724671 (code B ref 58813); Tue, 07 Mar 2023 11:36:02 +0000 Received: (at 58813) by debbugs.gnu.org; 7 Mar 2023 11:35:37 +0000 Received: from localhost ([127.0.0.1]:44693 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pZVbU-0006Pr-LL for submit@debbugs.gnu.org; Tue, 07 Mar 2023 06:35:37 -0500 Received: from mail-wm1-f50.google.com ([209.85.128.50]:46732) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pZVbR-0006Pc-P6 for 58813@debbugs.gnu.org; Tue, 07 Mar 2023 06:35:34 -0500 Received: by mail-wm1-f50.google.com with SMTP id l7-20020a05600c1d0700b003eb5e6d906bso6977427wms.5 for <58813@debbugs.gnu.org>; Tue, 07 Mar 2023 03:35:33 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; t=1678188927; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:from:to:cc:subject:date:message-id:reply-to; bh=l8jFFFH3vagAVYZSJp5vTEh6HYZLfa/hKI7ogF/IZlU=; b=cDdiAqCu010YOx1dPVJu3nVDA6Me92TImZ20WZTK9fPYiqXnXjGQAwHBCWwZT4mu7v gbqDWFON023FcnFC5O3Gw7LVV77ZONdJFhmSH4zQMZ/F5GXzIEXHyGrrszdlo6HGrZD+ aFgVM5tKdpouETV0wNw6hm6zlVVZ5+shiRhlGRgX506TA0IVOuvmkpEBZb+tTgdwkPXH O3W8c57nSaIn1k5omEVte/CfPA5ItUMu2JIBAW7c3eyNUbPZ+suLtQLfHgQ/UPwkFXM1 yebj7q1eS9JWO+XbMna/yiQHYpE6ws0O4/ukLOFRdj0yE1PjG5E2ExzWyezDny9/MPX2 n4zA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; t=1678188927; 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=l8jFFFH3vagAVYZSJp5vTEh6HYZLfa/hKI7ogF/IZlU=; b=g+DaHDFwD6ravo5yCA4KPXTU8ygNeKSDsjfwdg9Rov1JHukc4YSbIuYH4FeXxrjoQ7 uyE5wnzNX5sTPXvepxSOHb1AwJkZVEVt+nUGC33C9yg05Ssf/iJKLK7aUv3HF2laMuIz HRfOTU5win6GPvXZFE9LjUub8Ps/58YGSA3Hg0leZUTTToKqKH13DPu/iQwi91eeQ2u2 4R2vIbUvVVzj2JmR9mtq1siZuz2Awv8CcDc1+jF7Va4rzvt+szKsgU4iIGuqkOf0/iUj jg9xqpUDeyICAfpI5z7AD3U6OrCG0Jn6ReoTzZYURD85+TI9ysE/HdF2obGq6FFGGeIX sK0A== X-Gm-Message-State: AO0yUKXTTiM9bXco4uZgSAKtzlPnv0p2Zo3a8/jgkn/2M9+udehRhMyt wqzs6FUP9X7NgJ2VLSfiuaSkgF/xGhA= X-Google-Smtp-Source: AK7set+VXHUpusnf6CdPt8bOy1FfXUaqd0QtaLletmXIWSPz3gVRzmW1wZhDTouLjK73PFBg59lxwA== X-Received: by 2002:a05:600c:3b8b:b0:3e8:7ca3:8424 with SMTP id n11-20020a05600c3b8b00b003e87ca38424mr11064579wms.1.1678188927419; Tue, 07 Mar 2023 03:35:27 -0800 (PST) Received: from localhost.localdomain ([2a01:e0a:59b:9120:65d2:2476:f637:db1e]) by smtp.gmail.com with ESMTPSA id q14-20020a05600c46ce00b003daffc2ecdesm17360151wmo.13.2023.03.07.03.35.26 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 07 Mar 2023 03:35:27 -0800 (PST) From: Simon Tournier Date: Tue, 7 Mar 2023 12:35:24 +0100 Message-Id: <20230307113524.901320-1-zimon.toutoune@gmail.com> X-Mailer: git-send-email 2.38.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: X-Migadu-Scanner: scn0.migadu.com X-Migadu-Queue-Id: CA13117B93 X-Spam-Score: 7.79 X-Migadu-Spam-Score: 7.79 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 X-TUID: m7t/hItWlU6I From: Maxim Cournoyer Fixes . * doc/contributing.texi (Sending a Patch Series): Adjust the examples to no longer showcase broken command substitutions. (Patch management using patman): New section about how to use Patman, with examples. --- doc/contributing.texi | 111 ++++++++++++++++++++++++++++++++++++++++-- doc/guix.texi | 2 +- 2 files changed, 108 insertions(+), 5 deletions(-) Hi, My proposal is to have Patch management using patman as a dedicated section. This way, we keep the submission guidelines simple using good ol' git-send-email. And by being a dedicated section, it acts as the Perfect Setup: that's a tool very handy for doing the patch management task. WDYT? Cheers, simon diff --git a/doc/contributing.texi b/doc/contributing.texi index 61c05c2489..197f9719ba 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -1531,7 +1531,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 @@ -1545,7 +1545,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 @@ -1588,18 +1588,121 @@ 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 + +@node Patch management using @command{patman} +@subsection Patch management using @command{patman} +@cindex patman patch manager +@cindex patch management, via patman + +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}). + +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 6671ba9305..1fe03df3b7 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: 26e9725c54df48eda8282e6716a7581a7755f8f9 -- 2.38.1