From patchwork Wed Oct 19 22:00:48 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "\\(" X-Patchwork-Id: 43728 Return-Path: X-Original-To: patchwork@mira.cbaines.net Delivered-To: patchwork@mira.cbaines.net Received: by mira.cbaines.net (Postfix, from userid 113) id 01A0527BBEA; Wed, 19 Oct 2022 23:03:11 +0100 (BST) X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on mira.cbaines.net X-Spam-Level: X-Spam-Status: No, score=-3.7 required=5.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED,MAILING_LIST_MULTI,RCVD_IN_MSPIKE_H2,SPF_HELO_PASS, URIBL_BLOCKED autolearn=unavailable autolearn_force=no version=3.4.6 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mira.cbaines.net (Postfix) with ESMTPS id 6351D27BBE9 for ; Wed, 19 Oct 2022 23:03:10 +0100 (BST) Received: from localhost ([::1]:45158 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1olH9Z-0005Gv-HF for patchwork@mira.cbaines.net; Wed, 19 Oct 2022 18:03:09 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:50772) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1olH8U-0005EI-DU for guix-patches@gnu.org; Wed, 19 Oct 2022 18:02:03 -0400 Received: from debbugs.gnu.org ([209.51.188.43]:33052) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1olH8U-0004AG-44 for guix-patches@gnu.org; Wed, 19 Oct 2022 18:02:02 -0400 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1olH8T-0006cx-UH for guix-patches@gnu.org; Wed, 19 Oct 2022 18:02:01 -0400 X-Loop: help-debbugs@gnu.org Subject: [bug#58648] [PATCH 1/1] 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: Wed, 19 Oct 2022 22:02:01 +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.166621689125434 (code B ref 58648); Wed, 19 Oct 2022 22:02:01 +0000 Received: (at 58648) by debbugs.gnu.org; 19 Oct 2022 22:01:31 +0000 Received: from localhost ([127.0.0.1]:60363 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1olH7y-0006cA-UM for submit@debbugs.gnu.org; Wed, 19 Oct 2022 18:01:31 -0400 Received: from knopi.disroot.org ([178.21.23.139]:43216) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1olH7w-0006bw-AV for 58648@debbugs.gnu.org; Wed, 19 Oct 2022 18:01:29 -0400 Received: from localhost (localhost [127.0.0.1]) by disroot.org (Postfix) with ESMTP id 2345A4E8A9; Thu, 20 Oct 2022 00:01:27 +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 Vk-1iqy7RRgc; Thu, 20 Oct 2022 00:01:25 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=disroot.org; s=mail; t=1666216851; bh=FYnxkTHrqF0kM05U3XecCfaoGDjNzs3EyPZ6KGJM6XY=; h=From:To:Cc:Subject:Date; b=Q23oEbRxtomwtAliMF7KydSn02vug3kmlAJ9jUoKAg3ghcAx50RppCPAPaOHWfEuu uqJ408HdgXEvvhzOKhqtlOqvLfq2ciEg/ekceXN+k7OMO1xzwx0TDCuvQF17gUijeO OFEbJ3OVJD2wM87N4h8K0KXD2bB16xVO/k3a1Q2gqjIFzDFCEC9eReSl8XZKleBh5K TYzdYBZSycrb0NBd4bt8PO3U6VgMCH3yxJCMKI+eaYG3BkuIt7mqk9DveewWHRaEn8 3bBSwlQ2B0XqLR74y1QenuxEwD8/EdtPgjPmtBzkW+GUEtXk4NYjqr+9FwGn2MIQDT gDzyDM2bZrFyQ== Date: Wed, 19 Oct 2022 23:00:48 +0100 Message-Id: <20221019220048.24290-1-paren@disroot.org> Mime-Version: 1.0 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+patchwork=mira.cbaines.net@gnu.org Sender: "Guix-patches" Reply-to: "\(" X-ACL-Warn: , "\( via Guix-patches" X-Patchwork-Original-From: "\( via Guix-patches" via From: "\\(" X-getmail-retrieved-from-mailbox: Patches * doc/contributing.texi: Expand on sending patches and using git send-email. --- doc/contributing.texi | 83 ++++++++++++++++++++++++++++++++++++------- 1 file changed, 71 insertions(+), 12 deletions(-) diff --git a/doc/contributing.texi b/doc/contributing.texi index 4b1eed1cb1..c7a2dd09e7 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -1409,19 +1409,78 @@ git config --local sendemail.thread no @anchor{Sending a Patch Series} @cindex patch series @cindex @code{git send-email} +The @code{git send-email} and @code{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 +@code{git format-patch --cover-letter}. -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 - -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}). +@example +$ git format-patch -$N -o outgoing --cover-letter +@end example + +@quotation Note +The @code{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 @code{.patch} files in @code{outgoing/}, along with an automatically +generated cover letter. We can then send the cover letter to the Guix +mailing list. + +@example +$ git send-email outgoing/0000-cover-letter.patch -a --to guix-patches@@gnu.org +@end example + +Note the @code{-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. + +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 @code{@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 +@code{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 + +The use of the @code{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. + +To incorporate a reviewer's suggestions, use @code{git rebase -i} to amend +the commits, as demonstrated @url{https://git-rebase.io, here}, and send a +second patch series with a @code{-v2} tag. + +@example +$ git send-email -$N -v2 --to ISSUE_NUMBER@@debbugs.gnu.org +@end example + +Note that since we already have an issue on Debbugs for our patchset, +there's no need for the intermediate @code{git format-patch} step. Of +course, to send a third patchset, you amy use @code{-v3}, to send a fourth, +@code{-v4}, and so on. + +If need be, you may use @code{--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}