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 SEnzJW5hUWNPIAEAbAwnHQ (envelope-from ) for ; Thu, 20 Oct 2022 16:55:42 +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 iPYFJm5hUWNhLgEAauVa8A (envelope-from ) for ; Thu, 20 Oct 2022 16:55:42 +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 450E4321A7 for ; Thu, 20 Oct 2022 16:55:42 +0200 (CEST) Received: from localhost ([::1]:45252 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1olWxQ-0007zd-BF for larch@yhetil.org; Thu, 20 Oct 2022 10:55:40 -0400 Received: from [::1] (helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1olWsV-0007Wc-2O for larch@yhetil.org; Thu, 20 Oct 2022 10:50:35 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:56118) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1olWK7-0002RY-VW for guix-patches@gnu.org; Thu, 20 Oct 2022 10:15:15 -0400 Received: from debbugs.gnu.org ([209.51.188.43]:36808) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1olWK6-0008Rj-Ph for guix-patches@gnu.org; Thu, 20 Oct 2022 10:15:03 -0400 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1olWK6-0005zO-GT for guix-patches@gnu.org; Thu, 20 Oct 2022 10:15:02 -0400 X-Loop: help-debbugs@gnu.org Subject: [bug#58648] [PATCH v2] doc: contributing: Expand "Sending a Patch Series". References: <20221019215709.24201-1-paren@disroot.org> In-Reply-To: <20221019215709.24201-1-paren@disroot.org> Resent-From: "(" Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Thu, 20 Oct 2022 14:15:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 58648 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: 58648@debbugs.gnu.org Cc: "\(" Received: via spool by 58648-submit@debbugs.gnu.org id=B58648.166627526022958 (code B ref 58648); Thu, 20 Oct 2022 14:15:02 +0000 Received: (at 58648) by debbugs.gnu.org; 20 Oct 2022 14:14:20 +0000 Received: from localhost ([127.0.0.1]:35886 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1olWJN-0005yC-QG for submit@debbugs.gnu.org; Thu, 20 Oct 2022 10:14:20 -0400 Received: from knopi.disroot.org ([178.21.23.139]:40472) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1olWJJ-0005xy-5Q for 58648@debbugs.gnu.org; Thu, 20 Oct 2022 10:14:17 -0400 Received: from localhost (localhost [127.0.0.1]) by disroot.org (Postfix) with ESMTP id 528794E700; Thu, 20 Oct 2022 16:14:11 +0200 (CEST) X-Virus-Scanned: SPAM Filter at disroot.org Received: from knopi.disroot.org ([127.0.0.1]) by localhost (disroot.org [127.0.0.1]) (amavisd-new, port 10024) with UTF8SMTP id P8XfWrObuENx; Thu, 20 Oct 2022 16:14:09 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=disroot.org; s=mail; t=1666275235; bh=c+LiVrLIEGr/Sw+nmTtkM3zrG3OZeMt/vBRx5MYXu98=; h=From:To:Cc:Subject:Date; b=Z13xD//WR/ce0jm9jAWvRQWf3eG5NNueXwVn525dTfJONI8ZSwjPf0l50J4rhPqrs wxaemdR73mwRh0ITHC8KcfqKqXOWG/4j1zEur0xPXj487rV45o8+bhIzUMujsR+WlR DWkjCyY2cKtGBoxC/dy/biT7Whga6ukIoQyIZ84OkpqIesNCSsET/CEw+aGZTr16zT DCc+G3JCIUOjghqg+0y8fydHXknDZCyNr2LpHGzyCVlDI5bmEUNi2DMubca+lfYCDq Z3zVPfKk7AZ4ngWeiLrC/BnAAfazgl05pXwh+mpbRZgrv7nGYRzM3ESNKS9a8FNQnZ qSRchAmjSnAgw== Date: Thu, 20 Oct 2022 15:13:49 +0100 Message-Id: <20221020141349.4780-1-paren@disroot.org> Mime-Version: 1.0 Content-Transfer-Encoding: 8bit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: guix-patches@gnu.org List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+larch=yhetil.org@gnu.org Sender: "Guix-patches" Reply-to: "\(" X-ACL-Warn: , "\( via Guix-patches" From: "\( via Guix-patches" via X-Migadu-Flow: FLOW_IN X-Migadu-Country: US ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1666277742; h=from:from:sender:sender:reply-to:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: 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=ZP1OzfU+bxBCcJqg85aksHEV5uH7ejFd4UeJ3Fjp2O4=; b=py9BV7yGGpD7gpowcZpQ0l1COK4DfFtb/bKOBQp+YiRkOC6lt3VFl5y6QGuqOkNG3eQsT6 P5KHDZFz0738q2cWTffeS+tslDBp6sqU0hT8RyRIvFRR5Aa6ktfvHI4f/djsZV0q1EM+ia m4sYfn2M0NatqIsyxJXDi50fJWqFlhcdl+MLhJL5tgo6RfG58loFUXW5gS/KP5HiKa11tY arLOVbbhN4Jl/ScwiURrxS1YwJhzcBWEwfJxF6UjLoOMHa2dnCq6eFrfhy+Dn9yQWST/dk xDH9YF9mISRHDSCNH0/AJ+e5lli1hTUv7euh2zPFOHTrNPrcYk6t5VXsnSSlbw== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1666277742; a=rsa-sha256; cv=none; b=lkB/MRU9xgeyOKz2LPz4CbiPnxl114dgG2dHDvwTwhwhvp0uafBfpgpzCSuUXMZvXG6B7k gWmppHiMMAqqXtykN6IJu3Vsr9N9s2n76WjoRya/IvpKzuaStfHIZiabW11JlQuQ1V0fQh dh0vqik8GVWLIyyADMmOvAtSj2gDv3dQ7B0TpS9Q6x2/K6OumTveMnWt5HR2IWu2mIzvNe VIJfz5jfd/hvpH9KLetQ1NMqah/9zeZl+gsLif6fvWvJXoKR6mUnChh35yrZ4YjDtzcC4p M8Pv54jgD90r6zicC9LgclfRE1EdceMWKGZuqfAlLt1nZWYfcZHGhF+IZfB4mQ== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=disroot.org header.s=mail header.b="Z13xD//W"; dmarc=pass (policy=none) header.from=gnu.org; spf=pass (aspmx1.migadu.com: domain of "guix-patches-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-patches-bounces+larch=yhetil.org@gnu.org" X-Migadu-Spam-Score: -2.93 Authentication-Results: aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=disroot.org header.s=mail header.b="Z13xD//W"; dmarc=pass (policy=none) header.from=gnu.org; spf=pass (aspmx1.migadu.com: domain of "guix-patches-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-patches-bounces+larch=yhetil.org@gnu.org" X-Migadu-Queue-Id: 450E4321A7 X-Spam-Score: -2.93 X-Migadu-Scanner: scn0.migadu.com X-TUID: QuUVMuk+H1mF * doc/contributing.texi: Expand on sending patches and using git send-email. --- doc/contributing.texi | 120 ++++++++++++++++++++++++++++++------------ 1 file changed, 86 insertions(+), 34 deletions(-) diff --git a/doc/contributing.texi b/doc/contributing.texi index 4b1eed1cb1..650d3430fb 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -1149,15 +1149,6 @@ Before submitting a patch that adds or modifies a package definition, please run through this check list: @enumerate -@cindex @code{git format-patch} -@cindex @code{git-format-patch} -@item -When generating your patches with @code{git format-patch} or @code{git -send-email}, we recommend using the option @code{--base=}, perhaps with -the value @code{auto}. This option adds a note to the patch stating -which commit the patch is based on. This helps reviewers understand how -to apply and review your patches. - @item If the authors of the packaged software provide a cryptographic signature for the release tarball, make an effort to verify the @@ -1343,18 +1334,6 @@ a subject, if your patch is to be applied on a branch other than @code{master}, say @code{core-updates}, specify it in the subject like @samp{[PATCH core-updates] @dots{}}. -@quotation Tip -To add a prefix to the subject of your patch, you may use the -@option{--subject-prefix} option of the @command{git format-patch} or -@command{git send-email} commands, for example: -@example -git send-email --subject-prefix='PATCH core-updates' \ - --to=guix-patches@@gnu.org -1 -@end example -For more information, run @samp{man git-format-patch} and @samp{man -git-send-email}. -@end quotation - You may use your email client or the @command{git send-email} command (@pxref{Sending a Patch Series}). We prefer to get patches in plain text messages, either inline or as MIME attachments. You are advised to @@ -1409,19 +1388,92 @@ git config --local sendemail.thread no @anchor{Sending a Patch Series} @cindex patch series @cindex @code{git send-email} +The @command{git send-email} and @command{git format-patch} commands allow +you to send your commits in email form to a mailing list, to be reviewed +and applied, and they are the recommended way to submit contributions to +Guix. When you send the first revision of a patch series, it's best to use +@command{git format-patch --cover-letter}. + +@example +$ git format-patch -$N -o outgoing --cover-letter --base=HEAD~$N +@end example + +@quotation Note +The @command{git send-email} command is provided by the @code{send-email} +output of the @code{git} package, i.e. @code{git:send-email}. +@end quotation + +This command makes patches out of the last @var{N} commits, and writes +them to @file{*.patch} files in @file{outgoing/}, along with an +automatically generated cover letter. The @option{--base=HEAD~$N} option +adds @code{base-commit: @var{COMMIT}} to the bottom of the first email. + +We can now send the cover letter to the Guix mailing list, using +@command{git send-email}. + +@example +$ git send-email outgoing/0000-cover-letter.patch -a --to guix-patches@@gnu.org +@end example + +Note the @option{-a} flag; this pops up your editor so that you can fill +in the patchset subject line and blurb with whatever explanatory text you +feel is appropriate. Note the automatically generated shortlog and +diffstat below the blurb, which help to give potential reviewers an +overview of the patchset. + +@quotation Tip +To add a prefix to the subject of your patch, you may use the +@option{--subject-prefix} option. + +@example +git format-patch -$N -o outgoing \ + --subject-prefix='PATCH core-updates' \ + --base=auto --cover-letter +@end example +@end quotation + +The use of the @file{etc/teams.scm} script to notify the appropriate team +members (@pxref{Teams}) is recommended when submitting patches, to maximize +the chances of your patch series being reviewed quickly. + +At some point, the Debbugs mailer will reply to your cover letter mail +with an acknowledgement, which contains the issue number of your patchset. +You should now send the rest of the patches to this issue thread, using +the @email{@var{ISSUE_NUMBER}@@debbugs.gnu.org} address. + +@example +$ rm outgoing/0000-cover-letter.patch # Don't resend the cover letter! +$ git send-email outgoing/*.patch --to ISSUE_NUMBER@@debbugs.gnu.org +$ rm -rf outgoing # We're done with the patch files now. +@end example + +After a moment, your patches should appear at +@url{https://issues.guix.gnu.org/@var{ISSUE_NUMBER}} and +@url{https://debbugs.gnu.org/@var{ISSUE_NUMBER}}. + +@quotation Note +You should @strong{never} send all your patches to +@email{guix-patches@@gnu.org} at once, as this will create an issue for +each individual patch you send! If you do accidentally do this, though, +it's not a massive problem, as Debbugs supports merging issues. +@end quotation + +To incorporate a reviewer's suggestions, use @command{git rebase -i} to +amendthe commits, as demonstrated @url{https://git-rebase.io, here}, and +send a second patch series with a @option{-v2} tag. + +@example +$ git send-email -$N -v2 --base=auto --to ISSUE_NUMBER@@debbugs.gnu.org +@end example -When sending a patch series (e.g., using @code{git send-email}), please -first send one message to @email{guix-patches@@gnu.org}, and then send -subsequent patches to @email{@var{NNN}@@debbugs.gnu.org} to make sure -they are kept together. See -@uref{https://debbugs.gnu.org/Advanced.html, the Debbugs documentation} -for more information. You can install @command{git send-email} with -@command{guix install git:send-email}. -@c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html +Note that since we already have an issue on Debbugs for our patchset, +there's no need for the intermediate @command{git format-patch} step. Of +course, to send a third patchset, you amy use @option{-v3}, to send a +fourth, @option{-v4}, and so on. -To maximize the chances that you patch series is reviewed, the preferred -submission way is to use the @code{etc/teams.scm} script to notify the -appropriate team members (@pxref{Teams}). +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. @unnumberedsubsec Teams @anchor{Teams} @@ -1448,7 +1500,7 @@ You can run the following command to have the @code{Mentors} team put in CC of a patch series: @example -$ git send-email --to XXX@@debbugs.gnu.org $(./etc/teams.scm cc mentors) *.patch +$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org $(./etc/teams.scm cc mentors) *.patch @end example The appropriate team or teams can also be inferred from the modified @@ -1457,7 +1509,7 @@ current Git repository to review, you can run: @example $ guix shell -D guix -[env]$ git send-email --to XXX@@debbugs.gnu.org $(./etc/teams.scm cc-members HEAD~2 HEAD) *.patch +[env]$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org $(./etc/teams.scm cc-members HEAD~2 HEAD) *.patch @end example @node Tracking Bugs and Patches base-commit: 88746cd80bc56212ae7922c0fa1cd9a18e44c3bb -- 2.38.0