From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp11.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms5.migadu.com with LMTPS id 6NoYOEXfU2PzhQAAbAwnHQ (envelope-from ) for ; Sat, 22 Oct 2022 14:17:09 +0200 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp11.migadu.com with LMTPS id eP04OEXfU2MdCQEA9RJhRA (envelope-from ) for ; Sat, 22 Oct 2022 14:17:09 +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 92CCABF42 for ; Sat, 22 Oct 2022 14:17:09 +0200 (CEST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1omCZq-0002YI-NU; Sat, 22 Oct 2022 07:22:06 -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 1omCZm-0002VB-NH for guix-patches@gnu.org; Sat, 22 Oct 2022 07:22:02 -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 1omCZm-0005fR-GC for guix-patches@gnu.org; Sat, 22 Oct 2022 07:22:02 -0400 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1omCZm-0001QQ-3R for guix-patches@gnu.org; Sat, 22 Oct 2022 07:22:02 -0400 X-Loop: help-debbugs@gnu.org Subject: [bug#58648] [PATCH v2] doc: contributing: Expand "Sending a Patch Series". Resent-From: Liliana Marie Prikler Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Sat, 22 Oct 2022 11:22: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 Received: via spool by 58648-submit@debbugs.gnu.org id=B58648.16664377055438 (code B ref 58648); Sat, 22 Oct 2022 11:22:02 +0000 Received: (at 58648) by debbugs.gnu.org; 22 Oct 2022 11:21:45 +0000 Received: from localhost ([127.0.0.1]:39819 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1omCZU-0001PW-Np for submit@debbugs.gnu.org; Sat, 22 Oct 2022 07:21:45 -0400 Received: from mail-ed1-f66.google.com ([209.85.208.66]:36753) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1omCZQ-0001P4-BA for 58648@debbugs.gnu.org; Sat, 22 Oct 2022 07:21:42 -0400 Received: by mail-ed1-f66.google.com with SMTP id e18so14823131edj.3 for <58648@debbugs.gnu.org>; Sat, 22 Oct 2022 04:21:40 -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:to:from:subject:message-id:from:to:cc:subject:date :message-id:reply-to; bh=X/UqpsC0RwR4Np5UREmVxMidPNODmLmEOamP5wKelEY=; b=fCyNPpXlnUbeQgP3xIMZjXvpO9tyFZVM8YIv5q0f2YEET4RGmCFZ61pf7c5lJulW/s r6o7TtxvQ/+xg3AHR8xs55w2tbV4ETr4BJspj0moqUAeq2dTDeBTVMAdiiONpblG18OE /gKnX0G9HWGkAvEz66XqQ4iwuO+l73MiftTaUAFKDQp0WFCb08UKTBZVU2tBs6xMwanu MTRjNrMTUZQvcGwtH3h+xNaobw0m3QXAnY0I21M47V3Kr74GcNmUrHXGi+grq7wYsFxx QMh+gTYMLZLXnxwxU2NWCgwAhDIZAmaNxh0l+tqvWrhdbAEXHt58i5G32sBW6cTXq6xU rtVA== 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:to:from:subject:message-id:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to; bh=X/UqpsC0RwR4Np5UREmVxMidPNODmLmEOamP5wKelEY=; b=zoEhRxLW9CCwGZNDG4fwF8v6572gEQXmput8xWVz4RUdWTzFlT+psuIJwwc0bEI537 m75Yu4UE1ayCD73VnlPfyolY/OXAfAMeX5H9j5yxzD+6794kHtq88+HR+gixKiaMzfxz 76SqQrfd7cVEHDiaeHZsQlhN0yPTmFT1XxxwRzjlm1kMUtW5+2se2EhstStfqMLmuN+M 8+BmC15aVxckfgajedNrMEEbqm92sIVhpvrGPrC5cFUrClsGAVNEEilP5MNl7V9VW1+x oaPSNNzvxtrpkBNpXjYAUiSVB/TNjd+vMolJnnQ5ZzyaNkfbjNnv0g0JUpQg9Egdv1FF ViKg== X-Gm-Message-State: ACrzQf2wZH5Ac4V0GKXV74pvuoNGF1zs5l4jeG27TAfFlp6HlvI2cqMS Y9gLo7ZWw52iECwd+j0IE9Y= X-Google-Smtp-Source: AMsMyM7d345LsAlFb4yjpCxiZN/1Uky9E2/Dm91PdNl/e16J8VY7zaN+oRg6zzXYSnVIL+wLdQousw== X-Received: by 2002:a17:906:770d:b0:73c:a08f:593c with SMTP id q13-20020a170906770d00b0073ca08f593cmr20231309ejm.182.1666437693907; Sat, 22 Oct 2022 04:21:33 -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 ku16-20020a170907789000b0078ca30ee18bsm12911591ejc.95.2022.10.22.04.21.33 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 22 Oct 2022 04:21:33 -0700 (PDT) Message-ID: <9c9a4925aedab67b99f928084ecc7d46fda75f20.camel@gmail.com> From: Liliana Marie Prikler Date: Sat, 22 Oct 2022 13:21:30 +0200 In-Reply-To: <20221020141349.4780-1-paren@disroot.org> References: <20221020141349.4780-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=1666441029; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to: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=X/UqpsC0RwR4Np5UREmVxMidPNODmLmEOamP5wKelEY=; b=cVsZlqJuQXjaTt3eU49UmZW3twaVsYqMz9ZJIqSbWEqfUvjEJz+mGVmFdGdIcDAil/GLPr im9rZx+vuyarX+fFLR2cXZrE0frHZx9cSpNiSn7cn/7I9vsqAbJcnRafO+ARjm+oRbGnNE Ac7S6pz9JUyN1V6hT6GcgFJgQzTFri6MhgRGGI5Hxy9YrE4d+W8tTWwKNiSMRKWrIgA9l9 UKbXRns7vQ6VL0sigGYn1kxlss0fTD7TfDChbvXP5ayptD+r4Z3xka/lDPwsltYnrs58Qk z5XmA3JxShJFMpry/hrvc5+1umbGVwKFJRRLvgOZTRfwZ7x0hccAr/lqyPU0ZA== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1666441029; a=rsa-sha256; cv=none; b=hE/yNVsr0vv8Um2Ly8BQ8I9w5xlQdEEDjLko27NHaf1LQOoEhopfeNY5dtLDnxVC08uu5Q t3/c6ecFtoqHhpeDbUYKEBEMSMqzwJzJWj+J95WCKcryR2shWJneTzZj8g9BuxNIK/y6sG /6txb9GUQdc5EkkVJQsMsHVK6PWtLPA/cX1hjRQcHUJZE5PTA8ZqevYkWR8G/f9WpbiNCk WRdqoZmSjkJ0NM5J1X/hG8FYrMYIN/r9ymWgVjz5QZPDmElOk6l8NQT+Qa0bVCVcENAoDH AHeYZJVWrQLmcJbww+igPvP+QNS7k8AAQc9nLBwogn1X4eboHaKR53WEjU/Djg== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=gmail.com header.s=20210112 header.b=fCyNPpXl; 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: 7.56 Authentication-Results: aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=gmail.com header.s=20210112 header.b=fCyNPpXl; 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: 92CCABF42 X-Spam-Score: 7.56 X-Migadu-Scanner: scn1.migadu.com X-TUID: Tdkv0ks6vwaw Am Donnerstag, dem 20.10.2022 um 15:13 +0100 schrieb (: > * doc/contributing.texi: Expand on sending patches and using > =C2=A0 git send-email. > --- > =C2=A0doc/contributing.texi | 120 ++++++++++++++++++++++++++++++---------= - > -- > =C2=A01 file changed, 86 insertions(+), 34 deletions(-) >=20 > 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, > =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 > @@ -1409,19 +1388,92 @@ 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} > +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=3DHEAD~$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.=C2=A0 The @option{--base=3DHEAD~$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.=C2=A0 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 \ > +=C2=A0=C2=A0=C2=A0 --subject-prefix=3D'PATCH core-updates' \ > +=C2=A0=C2=A0=C2=A0 --base=3Dauto --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. I think you should also elaborate how this script is to be used. > +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!=C2=A0 If you do accidentally do this, > though, > +it's not a massive problem, as Debbugs supports merging issues. > +@end quotation Perhaps=C2=A0 @quotation Caution Do @strong{not} send all your patches at once, as this will create an issue for each individual patch. While Debbugs supports merging=C2=A0 issues, some interfaces (e.g. Mumi) still treat them as separate in certain ways, which can lower or exaggerate visibility and annoy reviewers. @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 amend the > +send a second patch series with a @option{-v2} tag. > + > +@example > +$ git send-email -$N -v2 --base=3Dauto --to > ISSUE_NUMBER@@debbugs.gnu.org > +@end example > =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 > +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. > =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 +1500,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 +1509,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 Also, this series makes it look as though we're only considering multi- patch series. Is the simple case of a single patch still covered? I'd perhaps organize this along these lines: - Sending a single patch - Notifying your senpais via etc/teams - Sending a multi-patch series Please don't take these headings too literally ;) Cheers