From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp10.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms5.migadu.com with LMTPS id wGJlMVg3WGOmSgAAbAwnHQ (envelope-from ) for ; Tue, 25 Oct 2022 21:22:00 +0200 Received: from aspmx1.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp10.migadu.com with LMTPS id UHR5MFg3WGOMoAAAG6o9tA (envelope-from ) for ; Tue, 25 Oct 2022 21:22:00 +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 7CA151B631 for ; Tue, 25 Oct 2022 21:22:00 +0200 (CEST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1onPS7-0006Bc-O2; Tue, 25 Oct 2022 15:19:07 -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 1onPS2-0005ez-LH for guix-patches@gnu.org; Tue, 25 Oct 2022 15:19:03 -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 1onPS2-0001RO-CQ for guix-patches@gnu.org; Tue, 25 Oct 2022 15:19:02 -0400 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1onPS2-0003pg-6z for guix-patches@gnu.org; Tue, 25 Oct 2022 15:19:02 -0400 X-Loop: help-debbugs@gnu.org Subject: [bug#58648] [PATCH v3] doc: contributing: Expand "Sending a Patch Series". Resent-From: Liliana Marie Prikler Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Tue, 25 Oct 2022 19:19: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: zimoun Received: via spool by 58648-submit@debbugs.gnu.org id=B58648.166672549914673 (code B ref 58648); Tue, 25 Oct 2022 19:19:02 +0000 Received: (at 58648) by debbugs.gnu.org; 25 Oct 2022 19:18:19 +0000 Received: from localhost ([127.0.0.1]:52316 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1onPRK-0003ob-34 for submit@debbugs.gnu.org; Tue, 25 Oct 2022 15:18:18 -0400 Received: from mail-ej1-f67.google.com ([209.85.218.67]:44741) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1onPRG-0003oF-Ng for 58648@debbugs.gnu.org; Tue, 25 Oct 2022 15:18:17 -0400 Received: by mail-ej1-f67.google.com with SMTP id n12so9892881eja.11 for <58648@debbugs.gnu.org>; Tue, 25 Oct 2022 12:18:14 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=mime-version:user-agent:content-transfer-encoding:references :in-reply-to:date:cc:to:from:subject:message-id:from:to:cc:subject :date:message-id:reply-to; bh=6O9pzXVFLaL5uPMVah2135wmDzvTX1S8f2PnQGry0gg=; b=Aj5aaQIbwehHMl8ctNpb9dV6WxSw0WxlLR3+6vH34lalI7ClrGLMHeMJThCEMmQRRr jolbXnj4iAknE+v5U/8mvuJh4HUJ1VCIvxUnZK5fCS1CHsSZFeaSO7y/N1gjqmQ6/AUo WyvXIA97V/2SMuauudIJtkAHaK9os0oaS/2k52nKie8sp7i8TJlxZGWK7iCWRhAbEuBC p0XWwrK5I8y2nmfGqps19h7cl9heZmhCNLZ2QXdCId5+bfUe08R6a2fiZmEBq+oA9zx5 oYRCYDKWVuHMlPzj3LyxnISAkt76lxOs8y5IWKvrJHYVHz7OIpISGVNOUMwDMAjK0Usx ZVog== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=mime-version:user-agent:content-transfer-encoding:references :in-reply-to:date:cc:to:from:subject:message-id:x-gm-message-state :from:to:cc:subject:date:message-id:reply-to; bh=6O9pzXVFLaL5uPMVah2135wmDzvTX1S8f2PnQGry0gg=; b=jJQhKKdtkE5PW2SYlUF8Yn7PCIXt3DsN6wqkbk/8mL+APR0UBXcp5Tt1CYOMn910Mi j9x7XS8bvYSFDEmWyJN/YNbg213KYcfnnOPNf/iSdvjtEu6Nqx8N7skZ6hTc+kF4ZSIK KbxNf7V65/sJRsjDA1TvJM7tSPPOiD/cL6HcdqZFNF4CcQ91oLFkK/+irJdiG3LpdHcI LOLoPz00Qe75wlFzdhoC5fAKcnAPZD4mHgwPQzhr8raGC27LUS0Pr5HsDJxr7bHXO03Y NcydFTojc0HqMPvFLd8FUn8Z9RclEk4OKid6bTsp7/KdI2m4ngSAnqrXt48RXy32OM0U RlKg== X-Gm-Message-State: ACrzQf119RqXdb3Zpks6IHDczqdHVe9xPMaCPk6e364Q6RZLKqR5ya/4 bDlul8gHHB8uIlLndab1UaU= X-Google-Smtp-Source: AMsMyM668N9cC9sqU2lgvzPbT60QCmK76c4Fw+/fsaSiHRoeZoOemHFpOVYbictueCMW1K67WIxEuQ== X-Received: by 2002:a17:907:7e95:b0:78d:e9cf:82c7 with SMTP id qb21-20020a1709077e9500b0078de9cf82c7mr34724475ejc.724.1666725488772; Tue, 25 Oct 2022 12:18:08 -0700 (PDT) Received: from lumine.fritz.box (85-127-52-93.dsl.dynamic.surfer.at. [85.127.52.93]) by smtp.gmail.com with ESMTPSA id b12-20020a1709063f8c00b0078d4e39d87esm1790121ejj.225.2022.10.25.12.18.08 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 25 Oct 2022 12:18:08 -0700 (PDT) Message-ID: <37b48f864a5e0ab4823a4441aa831bf2abb02fe1.camel@gmail.com> From: Liliana Marie Prikler Date: Tue, 25 Oct 2022 21:18:07 +0200 In-Reply-To: <20221025184251.8388-1-paren@disroot.org> References: <20221025184251.8388-1-paren@disroot.org> Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable User-Agent: Evolution 3.46.0 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: , Sender: "Guix-patches" 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=1666725720; 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=6O9pzXVFLaL5uPMVah2135wmDzvTX1S8f2PnQGry0gg=; b=bUpTeq6GWKLJKGKbkV76CYCzdgYSLyHZa83gNMtPvTdx+u9FFaCVM+Hrt86CjV0eQlw1ye s5dVatF50Atmtanp9MsSV48IHYDuEJRhWCepf9/zoNMRK8dzJAKBG3+G6HgfuebOlTXS0V j4P6XWqWZAntSGpXHr4f5BqOUSGR23WEd431zp14/eVKVbwXgSn/bZb2gjLU6FI60Z0F7k 94THSAQkPMn4V7lgUCzZFm/AjwDlRyK6iwglZeUHi9kR5Ie0t5odyuSNS/WdWEvVkQjqsK EEc/xWVWHAPTiIrbv6XMqrA8JMuRr6Sx75QUUYt84dGshbossxT+vpXFtJvqiA== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1666725720; a=rsa-sha256; cv=none; b=SgoxF7w9xl4GPDiR4z5uMCTU7+mO5sTi0hMbsIFe8E+vVZjLVQVOVLVMOvdYn2+q32PNs4 /0FeQD1PUQIowhcBRhmaiDxCnJVrG2iRnhbcWE+FdQD/iCrUtjev3H0uHFtRrJocR2+lDX whtetkQJfl1WUKOjI+bDwrBhEOCnEhcSphbbqj1ogwKQngBQByoV3a9BfnXwi+oQHvF6J7 D1kH/zcITPnfI1AUUFm2AqNrm0UmpW2D6NeWTaUjVmuPIN5nJzWr8n1bAIQnZTwbYbS0YB oxDyGj5jPP16NgzKnmlp+sKULLcaECGC+QaNJ47wEJpRDREC7yB0aXKPMkJtuA== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=gmail.com header.s=20210112 header.b=Aj5aaQIb; dmarc=fail reason="SPF not aligned (relaxed)" header.from=gmail.com (policy=none); 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: 4.79 Authentication-Results: aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=gmail.com header.s=20210112 header.b=Aj5aaQIb; dmarc=fail reason="SPF not aligned (relaxed)" header.from=gmail.com (policy=none); 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: 7CA151B631 X-Spam-Score: 4.79 X-Migadu-Scanner: scn0.migadu.com X-TUID: bSFzFhbQ5Yho Am Dienstag, dem 25.10.2022 um 19:42 +0100 schrieb (: > * doc/contributing.texi: Expand on sending patches and using > =C2=A0 git send-email. > --- > =C2=A0doc/contributing.texi | 173 +++++++++++++++++++++++++++++++++------= - > -- > =C2=A01 file changed, 136 insertions(+), 37 deletions(-) >=20 > 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 > =C2=A0keep track of submissions (@pxref{Tracking Bugs and Patches}).=C2= =A0 Each > =C2=A0message sent to that mailing list gets a new tracking number > assigned; > =C2=A0people 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}). > =C2=A0 > =C2=A0Please write commit logs in the ChangeLog format (@pxref{Change > Logs,,, > =C2=A0standards, 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, > =C2=A0please run through this check list: > =C2=A0 > =C2=A0@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=3D}, perhaps > with > -the value @code{auto}.=C2=A0 This option adds a note to the patch statin= g > -which commit the patch is based on.=C2=A0 This helps reviewers understan= d > how > -to apply and review your patches. > - > =C2=A0@item > =C2=A0If the authors of the packaged software provide a cryptographic > =C2=A0signature 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 > =C2=A0@code{master}, say @code{core-updates}, specify it in the subject > like > =C2=A0@samp{[PATCH core-updates] @dots{}}. > =C2=A0 > -@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=3D'PATCH core-updates' \ > -=C2=A0 --to=3Dguix-patches@@gnu.org -1 > -@end example > -For more information, run @samp{man git-format-patch} and @samp{man > -git-send-email}. > -@end quotation > - > =C2=A0You may use your email client or the @command{git send-email} > command > =C2=A0(@pxref{Sending a Patch Series}).=C2=A0 We prefer to get patches in= plain > =C2=A0text messages, either inline or as MIME attachments.=C2=A0 You are > advised to > @@ -1367,7 +1346,7 @@ acknowledgement with the assigned tracking > number. Future acknowledgements > =C2=A0should not be delayed. > =C2=A0 > =C2=A0When 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}. > =C2=A0 > =C2=A0@node Configuring Git > =C2=A0@subsection Configuring Git > @@ -1409,19 +1388,139 @@ git config --local sendemail.thread no > =C2=A0@anchor{Sending a Patch Series} > =C2=A0@cindex patch series > =C2=A0@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.=C2=A0 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=3Dauto --to=3Dguix-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.=C2=A0 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=3Dauto \ > +=C2=A0=C2=A0=C2=A0 --subject-prefix=3D'PATCH core-updates' \ > +=C2=A0=C2=A0=C2=A0 --to=3Dguix-patches@@gnu.org > +@end example > +@end quotation > =C2=A0 > -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.=C2=A0 See > -@uref{https://debbugs.gnu.org/Advanced.html, the Debbugs > documentation} > -for more information.=C2=A0 You can install @command{git send-email} wit= h > -@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.=C2=A0 You may ``annotate'' the patch with explanatory text by > adding > +it under this line.=C2=A0 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=3Dauto} 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=3Dauto -v @var{REVISION} \ > +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 --to=3D@var{ISSUE_NUMBER}@@debbugs.gnu.or= g > +@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 \ > +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 --cover-letter --base=3Dauto > +@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 \ > +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 --to=3Dguix-patches@@debbugs.gnu.org \ > +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 $(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.=C2=A0 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 \ > +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 --to=3D@var{ISSUE_NUMBER}@@debbugs.gnu.or= g \ > +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 $(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} \ > +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 -v@var{REVISION} --base=3Dauto \ > +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 --to @var{ISSUE_NUMBER}@@debbugs.gnu.org > +@end example > =C2=A0 > -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. > =C2=A0 > =C2=A0@unnumberedsubsec Teams > =C2=A0@anchor{Teams} > @@ -1448,7 +1547,7 @@ You can run the following command to have the > @code{Mentors} team put in > =C2=A0CC of a patch series: > =C2=A0 > =C2=A0@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 > =C2=A0@end example > =C2=A0 > =C2=A0The appropriate team or teams can also be inferred from the modifie= d > @@ -1457,7 +1556,7 @@ current Git repository to review, you can run: > =C2=A0 > =C2=A0@example > =C2=A0$ 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 > =C2=A0@end example > =C2=A0 > =C2=A0@node Tracking Bugs and Patches >=20 > base-commit: 88746cd80bc56212ae7922c0fa1cd9a18e44c3bb LGTM. Also CC'd zimoun