From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp11.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 uOQBICUxWGN+QAAAbAwnHQ (envelope-from ) for ; Tue, 25 Oct 2022 20:55:33 +0200 Received: from aspmx1.migadu.com ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp11.migadu.com with LMTPS id 4K77HyUxWGNsaQAA9RJhRA (envelope-from ) for ; Tue, 25 Oct 2022 20:55:33 +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 374C43C667 for ; Tue, 25 Oct 2022 20:55:33 +0200 (CEST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1onP4r-0005jx-MA; Tue, 25 Oct 2022 14:55:05 -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 1onP4p-0005UZ-U9 for guix-patches@gnu.org; Tue, 25 Oct 2022 14:55:04 -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 1onP4o-0005jL-1x for guix-patches@gnu.org; Tue, 25 Oct 2022 14:55:02 -0400 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1onP4n-00011z-Tt for guix-patches@gnu.org; Tue, 25 Oct 2022 14:55:01 -0400 X-Loop: help-debbugs@gnu.org Subject: [bug#58648] [PATCH v3] 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: Tue, 25 Oct 2022 18:55: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.16667240773929 (code B ref 58648); Tue, 25 Oct 2022 18:55:01 +0000 Received: (at 58648) by debbugs.gnu.org; 25 Oct 2022 18:54:37 +0000 Received: from localhost ([127.0.0.1]:52269 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1onP4O-00011J-RK for submit@debbugs.gnu.org; Tue, 25 Oct 2022 14:54:37 -0400 Received: from knopi.disroot.org ([178.21.23.139]:40890) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1onP4M-000117-Do for 58648@debbugs.gnu.org; Tue, 25 Oct 2022 14:54:35 -0400 Received: from localhost (localhost [127.0.0.1]) by disroot.org (Postfix) with ESMTP id 17DB14ECF4; Tue, 25 Oct 2022 20:54:33 +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 23l8221nkThz; Tue, 25 Oct 2022 20:54:31 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=disroot.org; s=mail; t=1666723381; bh=36LhRwBWHolFXj9rihido6o62mm4kMh8z2xKbLmPmQk=; h=From:To:Cc:Subject:Date; b=Py+Ft94njtutHmsuiXeAWB8Km/ahnSQOciDo6zZexokPjtx8L10uzcuYtlt3MKyUU ToMaOym4M/S0RATcJ/B1eFKCdmgfkRmwrsfhi3WvclumJwZ694yBP2+ATPPhP39R9o 0cbxztXX360tVaKkRPmI4XGlYiSv8Y04nj8xX6fjObBUCdQ5n++RKL4qezTm7LON4/ VRtkJZ9Njj0YLi/UNRM3mIjTrdjbDyr/D2yy3xNiR8s6IqgcobFhVL9tpaepaXNDNB VFEnfWSGzba/cj+aXOAVpjLJAB6qk55QgzqooPp2aV+8zizKEw0+almETZeT/4cHrU U9HFIghq2ggnQ== Date: Tue, 25 Oct 2022 19:42:51 +0100 Message-Id: <20221025184251.8388-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: , Sender: "Guix-patches" Reply-to: "\(" X-ACL-Warn: , "\( via Guix-patches" From: "\( via Guix-patches" via Errors-To: guix-patches-bounces+larch=yhetil.org@gnu.org 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=1666724133; 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=vBPSYHmGWe7KxeXBCLeDLNQHjNkCQEjB7IXdOPXA52g=; b=jOHSPoY0Xa02kkkfLdB7spkuCJQ7CJp36YZPQdYfCx7lv41fz4SQbBtSn97pEVVDCdhfL7 tmJfC9I+HuMIhxo7gfgncE/eXNy72odi7ME7LVd5XMlEJ8n5r6AhBpYJ//KjHh2v/EfGR2 nA7OZh2VrNJOihO3lWHteShKy6pj4944BeceS+/4qlyMTbGoRjm4kTnAGJ2xLVQf0uw2F4 HoO70ebgrvKs/Qpq/26XndmHFuzUKeRsYI3CrrljD/rXzhWDbiGBANjab3KPVAvZoDBWca LqG8zhaWq/UO11paGljPqnoCoK1aXiEP4y4x9MvqQxKtn6koHBenp8LnHEUJpg== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1666724133; a=rsa-sha256; cv=none; b=prCb+HL40LsSI4dMDWo9hiWOxTTEYTGweD8iCGNGaJ2CZ8ZDf8g0P6DiA3RYpAI3RoV2Vc hmoHlNzxeMLvcN80enTVQzBoW/BMIar4B49arVPHvYfxHlYzfyxQQDRX8bIiqAHp9Ynwqw UZWDpz7FbM+UJ6IUgWBfq1zCvrKP+sa6aZ0ZR00xU2d3oCeB7HQfnmWRyU+Y/zEbRwlJ84 5Ewps9Bo8ekqc3qJJ6rrIVvUs5nkWTb4nVHgzx0TWffGqNgb+rPS2rnwQul7Eq60RoAY8y z3ehVhDAdkgi7NYnLNzgb5fNQ/S+yx9ZEk7FIWdoorPlnDbNDtpS2HURaeiaIQ== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=disroot.org header.s=mail header.b=Py+Ft94n; 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.41 Authentication-Results: aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=disroot.org header.s=mail header.b=Py+Ft94n; 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: 374C43C667 X-Spam-Score: -2.41 X-Migadu-Scanner: scn1.migadu.com X-TUID: Q6wdkSVRkE0q * doc/contributing.texi: Expand on sending patches and using git send-email. --- doc/contributing.texi | 173 +++++++++++++++++++++++++++++++++--------- 1 file changed, 136 insertions(+), 37 deletions(-) diff --git a/doc/contributing.texi b/doc/contributing.texi index 4b1eed1cb1..9770018521 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -1138,8 +1138,8 @@ This mailing list is backed by a Debbugs instance, which allows us to keep track of submissions (@pxref{Tracking Bugs and Patches}). Each message sent to that mailing list gets a new tracking number assigned; people can then follow up on the submission by sending email to -@code{@var{NNN}@@debbugs.gnu.org}, where @var{NNN} is the tracking -number (@pxref{Sending a Patch Series}). +@code{@var{ISSUE_NUMBER}@@debbugs.gnu.org}, where @var{ISSUE_NUMBER} is +the tracking number (@pxref{Sending a Patch Series}). Please write commit logs in the ChangeLog format (@pxref{Change Logs,,, standards, GNU Coding Standards}); you can check the commit history for @@ -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 @@ -1367,7 +1346,7 @@ acknowledgement with the assigned tracking number. Future acknowledgements should not be delayed. When a bug is resolved, please close the thread by sending an email to -@email{@var{NNN}-done@@debbugs.gnu.org}. +@email{@var{ISSUE_NUMBER}-done@@debbugs.gnu.org}. @node Configuring Git @subsection Configuring Git @@ -1409,19 +1388,139 @@ git config --local sendemail.thread no @anchor{Sending a Patch Series} @cindex patch series @cindex @code{git send-email} +@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. + +@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 + +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: + +@example +$ git send-email -1 -a --base=auto --to=guix-patches@@gnu.org +@end example + +@quotation Tip +To add a prefix to the subject of your patch, you may use the +@option{--subject-prefix} option. The Guix project uses this to +specify that the patch is intended for a branch or repository +other than the @code{master} branch of +@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 +@end example +@end quotation -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 +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. + +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}. + +@example +$ git commit -a +$ git send-email -1 -a --base=auto -v @var{REVISION} \ + --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org +@end example + +You can find out @var{ISSUE_NUMBER} either by searching on the mumi +interface at @url{issues.guix.gnu.org} for the name of your patch or +reading the acknowledgement email sent automatically by Debbugs in +reply to incoming bugs and patches, which contains the bug number. + +@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. + +@unnumberedsubsubsec Multiple Patches +@anchor{Multiple Patches} +@cindex cover letter +While @command{git send-email} alone will suffice for a single +patch, an unfortunate flaw in Debbugs means you need to be more +careful when sending multiple patches: if you send them all to the +@email{guix-patches@@gnu.org} address, a new issue will be created +for each patch! + +When sending a series of patches, it's best to send a Git ``cover +letter'' first, to give reviewers an overview of the patch series. +We can create a directory called @file{outgoing} containing both +our patch series and a cover letter called @file{0000-cover-letter.patch} +with @command{git format-patch}. + +@example +$ git format-patch -@var{NUMBER_COMMITS} -o outgoing \ + --cover-letter --base=auto +@end example + +We can now send @emph{just} the cover letter to the +@email{guix-patches@@gnu.org} address, which will create an issue +that we can send the rest of the patches to. + +@example +$ git send-email outgoing/0000-cover-letter.patch -a \ + --to=guix-patches@@debbugs.gnu.org \ + $(etc/teams.scm cc-members ...) +$ rm outgoing/0000-cover-letter.patch # we don't want to resend it! +@end example + +Ensure you edit the email to add an appropriate subject line and +blurb before sending it. Note the automatically generated shortlog +and diffstat below the blurb. + +Once the Debbugs mailer has replied to your cover letter email, you +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 ...) +$ rm -rf outgoing # we don't need these anymore +@end example + +Thankfully, this @command{git format-patch} dance is not necessary +to send an amended patch series, since an issue already exists for +the patchset. + +@example +$ git send-email -@var{NUMBER_COMMITS} \ + -v@var{REVISION} --base=auto \ + --to @var{ISSUE_NUMBER}@@debbugs.gnu.org +@end example -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 +1547,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 +1556,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