From patchwork Wed May 11 01:47:30 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Philippe Blain X-Patchwork-Id: 12845683 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id A9E68C433F5 for ; Wed, 11 May 2022 01:47:49 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S239532AbiEKBrq (ORCPT ); Tue, 10 May 2022 21:47:46 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:45134 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231992AbiEKBrm (ORCPT ); Tue, 10 May 2022 21:47:42 -0400 Received: from mail-wr1-x434.google.com (mail-wr1-x434.google.com [IPv6:2a00:1450:4864:20::434]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 316EB25E2 for ; Tue, 10 May 2022 18:47:41 -0700 (PDT) Received: by mail-wr1-x434.google.com with SMTP id q23so925420wra.1 for ; Tue, 10 May 2022 18:47:41 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=message-id:in-reply-to:references:from:date:subject:fcc :content-transfer-encoding:mime-version:to:cc; bh=7vkdic47aCI4KAByIy33HpQVJzKc8wog5ekF2uIKc1U=; b=owC8z+7z0mpdJ5lhvRTQgXKPJsYMOGBfNFWEvXV06FswqBSqNdulqWM1jvl9mMIuCM 6zGrvKSQMdYrkQSk6cToOdmwYzWR9eyRuYlvVGLRI95o+bh2yaKFWQYTNwJWlkINIlqm xuoCa2RI6gcV0h2jMoUqP6mod386UZFZyaWiOYLVXvKJa0mMIjCrs6LfHa4Nsvuj7Bfa Ic8zVPwGgAzFTx/h/KwT19RUT9j2D7DqeNM7cW28MUghnQ1ziBKovvlOEJgHcr503Wcn /Txs+mG9tu0uTFyK6aUWFvQkeCD6ND141WrKEAm/QI0SFeQ1xJl6zusfKzIDQm3aDzU7 gN/g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:message-id:in-reply-to:references:from:date :subject:fcc:content-transfer-encoding:mime-version:to:cc; bh=7vkdic47aCI4KAByIy33HpQVJzKc8wog5ekF2uIKc1U=; b=PNdiU9FM+0mwk/ytoSWsySBBr5SMVUq3CbVwEIenE9QtwrPIrdUdfT4MKub1i3AllE 14RitxnqDBdHz0x+BDkt3/fQACo4Md8WEubuDvSTn2ueLCkmOjDgPTJGzdDdtlVnb+lt fK8UKLU4D2UrwsgNUAyNwLSao+yUQZV49bmpZ78EfUKR03ExVI/gipzJixW+yYPlIkJF omIu5T/Tc3OoaQmz6iKc0UQ+lh0qF7hbPA2IdX52hkpPS5j0ZHjQEeiTUo9/z/kZIZDK 0MJ/MdboOS8++vuUU7k1+UGu0m1+wSG47p+2shZz3zwle7HJEMbCqnGYp1fsPU5vRfNT mSQA== X-Gm-Message-State: AOAM5337vxX9JTrhPF0arC0aXtP9+rEbntXNetZrLWGPNQygwUTS7cM+ 18dgtF75xcVqnS2q+yC7AfPVGxbuuyk= X-Google-Smtp-Source: ABdhPJwZGTRpCQ87YSfehlwFl47acd7Xsn5oahSTY/apnryjxF5eut0c8vP/KDA8ZWQc5/9SO5HqKg== X-Received: by 2002:a05:6000:1841:b0:20c:788b:9306 with SMTP id c1-20020a056000184100b0020c788b9306mr19888426wri.369.1652233659345; Tue, 10 May 2022 18:47:39 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id v124-20020a1cac82000000b003946433a829sm701826wme.11.2022.05.10.18.47.37 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 10 May 2022 18:47:38 -0700 (PDT) Message-Id: <59af7e5e5ad84103b39ac9511791eb06b88df3c6.1652233654.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Wed, 11 May 2022 01:47:30 +0000 Subject: [PATCH v2 1/5] MyFirstContribution: add "Anatomy of a Patch Series" section Fcc: Sent MIME-Version: 1.0 To: git@vger.kernel.org Cc: Emily Shaffer , Johannes Schindelin , Victoria Dye , Eric Sunshine , Philippe Blain , Philippe Blain , Philippe Blain Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org From: Philippe Blain From: Philippe Blain Before describing how to send patches to the mailing list either with GitGitGadget or 'git send-email', the MyFirstContribution tutorial includes a small "Getting Ready to Share" section where the two different methods are briefly introduced. Use this section to also describe what a patch series looks like once submitted, so that readers get an understanding of the end result before diving into how to accomplish that end result. Start by copying the "thread overview" section of a recent contribution from the public-inbox web UI and explaining how each commit is a separate mail, and point out the cover letter. Subsequent commits will move the existing description of the purpose of the cover letter from the 'git send-email' section to this "anatomy" section. Also, change the wording in the introductory paragraph to use "contributions" instead of "patches", since this makes more sense when talking about GitHub pull requests. Signed-off-by: Philippe Blain --- Documentation/MyFirstContribution.txt | 54 +++++++++++++++++++++++++-- 1 file changed, 51 insertions(+), 3 deletions(-) diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt index 63a2ef54493..22848f84bec 100644 --- a/Documentation/MyFirstContribution.txt +++ b/Documentation/MyFirstContribution.txt @@ -710,13 +710,61 @@ dependencies. `prove` also makes the output nicer. Go ahead and commit this change, as well. [[ready-to-share]] -== Getting Ready to Share +== Getting Ready to Share: Anatomy of a Patch Series You may have noticed already that the Git project performs its code reviews via emailed patches, which are then applied by the maintainer when they are ready -and approved by the community. The Git project does not accept patches from +and approved by the community. The Git project does not accept contributions from pull requests, and the patches emailed for review need to be formatted a -specific way. At this point the tutorial diverges, in order to demonstrate two +specific way. + +:patch-series: https://lore.kernel.org/git/pull.1218.git.git.1645209647.gitgitgadget@gmail.com/ +:lore: https://lore.kernel.org/git/ + +Before taking a look at how to convert your commits into emailed patches, +let's analyze what the end result, a "patch series", looks like. Here is an +{patch-series}[example] of the summary view for a patch series on the web interface of +the {lore}[Git mailing list archive]: + +---- +2022-02-18 18:40 [PATCH 0/3] libify reflog John Cai via GitGitGadget +2022-02-18 18:40 ` [PATCH 1/3] reflog: libify delete reflog function and helpers John Cai via GitGitGadget +2022-02-18 19:10 ` Ævar Arnfjörð Bjarmason [this message] +2022-02-18 19:39 ` Taylor Blau +2022-02-18 19:48 ` Ævar Arnfjörð Bjarmason +2022-02-18 19:35 ` Taylor Blau +2022-02-21 1:43 ` John Cai +2022-02-21 1:50 ` Taylor Blau +2022-02-23 19:50 ` John Cai +2022-02-18 20:00 ` // other replies ellided +2022-02-18 18:40 ` [PATCH 2/3] reflog: call reflog_delete from reflog.c John Cai via GitGitGadget +2022-02-18 19:15 ` Ævar Arnfjörð Bjarmason +2022-02-18 20:26 ` Junio C Hamano +2022-02-18 18:40 ` [PATCH 3/3] stash: call reflog_delete from reflog.c John Cai via GitGitGadget +2022-02-18 19:20 ` Ævar Arnfjörð Bjarmason +2022-02-19 0:21 ` Taylor Blau +2022-02-22 2:36 ` John Cai +2022-02-22 10:51 ` Ævar Arnfjörð Bjarmason +2022-02-18 19:29 ` [PATCH 0/3] libify reflog Ævar Arnfjörð Bjarmason +2022-02-22 18:30 ` [PATCH v2 0/3] libify reflog John Cai via GitGitGadget +2022-02-22 18:30 ` [PATCH v2 1/3] stash: add test to ensure reflog --rewrite --updatref behavior John Cai via GitGitGadget +2022-02-23 8:54 ` Ævar Arnfjörð Bjarmason +2022-02-23 21:27 ` Junio C Hamano +// continued +---- + +We can note a few things: + +- Each commit is sent as a separate email, with the commit message title as + subject, prefixed with "[PATCH _i_/_n_]" for the _i_-th commit of an + _n_-commit series. +- Each patch is sent as a reply to an introductory email called the _cover + letter_ of the series, prefixed "[PATCH 0/_n_]". +- Subsequent iterations of the patch series are labelled "[PATCH v2]", "[PATCH + v3]", etc. and sent with a new cover letter, itself a reply to the cover + letter of the previous iteration (more on that below). + +At this point the tutorial diverges, in order to demonstrate two different methods of formatting your patchset and getting it reviewed. The first method to be covered is GitGitGadget, which is useful for those From patchwork Wed May 11 01:47:31 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Philippe Blain X-Patchwork-Id: 12845684 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 483AAC433F5 for ; Wed, 11 May 2022 01:47:52 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S240665AbiEKBru (ORCPT ); Tue, 10 May 2022 21:47:50 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:45254 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S235613AbiEKBrp (ORCPT ); Tue, 10 May 2022 21:47:45 -0400 Received: from mail-wm1-x335.google.com (mail-wm1-x335.google.com [IPv6:2a00:1450:4864:20::335]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id DF73FB7C9 for ; Tue, 10 May 2022 18:47:42 -0700 (PDT) Received: by mail-wm1-x335.google.com with SMTP id p189so337034wmp.3 for ; Tue, 10 May 2022 18:47:42 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=message-id:in-reply-to:references:from:date:subject:fcc :content-transfer-encoding:mime-version:to:cc; bh=1sKa3vnsehTwBo+B3VB+gR17FLImq6uo4R52FY4QKyA=; b=nR4TbKdRS5ye+eBT2pGgqjqvSCWn4E29AWoBteauypTaQi/Pnx1O4lCnmIkuwOgflD GnA4JO5A2/TeLl3j6PwxpZkvlNtLbsw2kdfofRO3ihe5KcBmSdZjaBigJvItrx7GgY7W JfXFz1jQ/J7jMzhG267YeTxEEIwBxs8WfW5dcv+D0zZ0yzaj9Ub74GJGP9d98Zh+v1+z uuT4KA4n3xnv6TITDBhi/4vVJgYGCWMgTk+chElDiA8R/GP//3YPQZSAqLhsy/1e2P+R Q85OJEww1Av+wg5VdTE8HuqD45ZEc8lHN7BZKfgUalWl1oL9jWduP86F44By6Z4UgbgV EHwA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:message-id:in-reply-to:references:from:date :subject:fcc:content-transfer-encoding:mime-version:to:cc; bh=1sKa3vnsehTwBo+B3VB+gR17FLImq6uo4R52FY4QKyA=; b=F5OCF6Vt9POoGBBdooDSPrgzX7GiWabXalF2EjWauCOm3a+GRop0oK5PEsDcs2ynb/ wtgLQbEgECIgQ+xy7B+gVeR7Z95dNUfpQAk+he45h5H5atMYNeZ1qweQ6IlGDg9Q9Nl0 dYbjoAhuXdvmjLQlwVyTd1pccCkGdTmwqCOb5ZP/eAapF418f1RekhspfgjAJWmaAyYu o+tKUYA8XdBnwtBlJk2U03/H5oAmJx2l/4i06tF1lsZag/iuxbwAtlBSwpuMZqm93k4l Micq/JORBk+OhmXgvQgdFBA5ETNgMloNX+vpMMWb6yQAViE0uQil598CVCtNs9Jwbmsw QDlA== X-Gm-Message-State: AOAM530igQpxLmejwV9XXIfyjgqKsnV6ty3xEHufKF6niGCU4VTlxxWz NO7BMmssuQEahFE3i4GMKWvcwWKoFaA= X-Google-Smtp-Source: ABdhPJx9Mqw95IQX2woZLSZlFujiSi0VQs9ID9fuC5aVqwoeRUXeGaW8m1EfJWqw/lh6nwFFWXhLxg== X-Received: by 2002:a7b:c086:0:b0:393:f6fa:cfc7 with SMTP id r6-20020a7bc086000000b00393f6facfc7mr2486147wmh.62.1652233661145; Tue, 10 May 2022 18:47:41 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id p2-20020a5d4e02000000b0020c5253d922sm316568wrt.110.2022.05.10.18.47.39 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 10 May 2022 18:47:40 -0700 (PDT) Message-Id: <9552d80a80d9574c8f256696fad06f48b39b51c9.1652233654.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Wed, 11 May 2022 01:47:31 +0000 Subject: [PATCH v2 2/5] MyFirstContribution: add standalone section on cover letter Fcc: Sent MIME-Version: 1.0 To: git@vger.kernel.org Cc: Emily Shaffer , Johannes Schindelin , Victoria Dye , Eric Sunshine , Philippe Blain , Philippe Blain , Philippe Blain Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org From: Philippe Blain From: Philippe Blain An explanation of the purpose of the cover letter is included in the "Sending Patches with git send-email" / "Preparing Email" section but is missing from the "Sending Patches via GitGitGadget" section. Add a standalone section "The cover letter" under the "Getting Started: Anatomy of a Patch Series" header to explain what the cover letter is used for and to draft the cover letter of the 'psuh' topic used in the tutorial. For now we mostly copy content from the "Sending Patches with git send-email" section but do not adjust that section, nor the GGG section, to reference the new section. This is done in following commits. Also, adjust the "Preparing Email" Asciidoc anchor to avoid conflicts. Signed-off-by: Philippe Blain --- Documentation/MyFirstContribution.txt | 39 ++++++++++++++++++++++++++- 1 file changed, 38 insertions(+), 1 deletion(-) diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt index 22848f84bec..de62a61771c 100644 --- a/Documentation/MyFirstContribution.txt +++ b/Documentation/MyFirstContribution.txt @@ -764,6 +764,43 @@ We can note a few things: v3]", etc. and sent with a new cover letter, itself a reply to the cover letter of the previous iteration (more on that below). +[[cover-letter]] +=== The cover letter + +In addition to an email per patch, the Git community also expects your patches +to come with a cover letter. This is an important component of change +submission as it explains to the community from a high level what you're trying +to do, and why, in a way that's more apparent than just looking at your +patches. + +The title of your cover letter should be something which succinctly covers the +purpose of your entire topic branch. It's often in the imperative mood, just +like our commit message titles. Here is how we'll title our series: + +--- +Add the 'psuh' command +--- + +The body of the cover letter is used to give additional context to reviewers. +Be sure to explain anything your patches don't make clear on their own, but +remember that since the cover letter is not recorded in the commit history, +anything that might be useful to future readers of the repository's history +should be in your commit messages, not in your cover letter. + +Here's an example body for `psuh`: + +---- +Our internal metrics indicate widespread interest in the command +git-psuh - that is, many users are trying to use it, but finding it is +unavailable, using some unknown workaround instead. + +The following handful of patches add the psuh command and implement some +handy features on top of it. + +This patchset is part of the MyFirstContribution tutorial and should not +be merged. +---- + At this point the tutorial diverges, in order to demonstrate two different methods of formatting your patchset and getting it reviewed. @@ -1000,7 +1037,7 @@ but want reviewers to look at what they have so far. You can add this flag with Check and make sure that your patches and cover letter template exist in the directory you specified - you're nearly ready to send out your review! -[[cover-letter]] +[[preparing-cover-letter]] === Preparing Email In addition to an email per patch, the Git community also expects your patches From patchwork Wed May 11 01:47:32 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Philippe Blain X-Patchwork-Id: 12845685 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 0FEF5C433EF for ; Wed, 11 May 2022 01:48:01 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S240655AbiEKBsA (ORCPT ); Tue, 10 May 2022 21:48:00 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:45404 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S240637AbiEKBrr (ORCPT ); Tue, 10 May 2022 21:47:47 -0400 Received: from mail-wr1-x42f.google.com (mail-wr1-x42f.google.com [IPv6:2a00:1450:4864:20::42f]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id B6B6625E2 for ; Tue, 10 May 2022 18:47:44 -0700 (PDT) Received: by mail-wr1-x42f.google.com with SMTP id k2so906742wrd.5 for ; Tue, 10 May 2022 18:47:44 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=message-id:in-reply-to:references:from:date:subject:fcc :content-transfer-encoding:mime-version:to:cc; bh=zOv2Y4JSjAQ+XIqTP8yGgN/I5/3fvybJEvtQtlez+lQ=; b=Kk/9kswKfxJEi5Wj4soWR6UjggZO4k7kIv64yTg0LRJAm8kuiJ0nPRemNrofOuloGc gsoAArZtQ4rXUosnmzf0mlIzAAkvzfMGae7s/kUkFuJN74Ml6ZNeX/RUojd8d0C0a+Sy xAU2IFqDe+C2m3oQn0DbXSJ+g3dVnE2f0td8QEwbFx1B2Hgqbhf+T9DcUJOjyufLPMB9 kNEZsl3qmZewH/dsds4yRHaj6wHuJzTJb2JuBNkxD329z4aq8B+IoEtoKpYPSfdL+vnR KBcTn1tPf1a+lCT8StiWYa8LkZIGgpNwV8ar0/fIs/3SI++vXW+3N9Yypjzgb/JD/GkH T5yg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:message-id:in-reply-to:references:from:date :subject:fcc:content-transfer-encoding:mime-version:to:cc; bh=zOv2Y4JSjAQ+XIqTP8yGgN/I5/3fvybJEvtQtlez+lQ=; b=JYKNVFMjRkDeIIUBhxx/u8q3t0X2pgicLusHAZPhOCbrp5NMjsST/6JtQQdyhI5aj6 P8FmsPN//3yjEaCr3SK9coq0EWlDmOEpb1NZIiRzpsyFFb3yxuBVkdf4jhBbc3npKC90 7LMS/EO6ifz3UmvrsErxglbSH1glG0jBcHHy33EX699roOYSztzVdrQ20o8/TSgG1olT ypWMZtG3JiyrCYJEyc1Ww1IqriSj59rc8yYoUrgTcGFaA/XXGGqGYdZyivfU6SbRZqYT Cpp4E7+ioEJ4XXrrFszkG9Hf8okoAqpoqOy3vzPyrWdk+eADkW1vxqZ2jznBzrvcJrPX 0cPw== X-Gm-Message-State: AOAM532pOxI/lKUphKlMKRas1QvHd9mZOf2dbgdEF1gMW5d9VUI2BgU2 MuD0ierlsN0IFXCGN8gRSUSR10sZ77g= X-Google-Smtp-Source: ABdhPJxE2C6AVipwgsC2/NvSJaTUgFqiNJinCGn68PCbTulNm3mt5/v/57l0rqi38+Vz28YZyF+0BQ== X-Received: by 2002:a5d:6792:0:b0:20a:d352:10de with SMTP id v18-20020a5d6792000000b0020ad35210demr21070700wru.326.1652233662943; Tue, 10 May 2022 18:47:42 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id e18-20020a05600c4e5200b003958af7d0c8sm658702wmq.45.2022.05.10.18.47.41 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 10 May 2022 18:47:41 -0700 (PDT) Message-Id: In-Reply-To: References: Date: Wed, 11 May 2022 01:47:32 +0000 Subject: [PATCH v2 3/5] MyFirstContribution: reference "The cover letter" in "Preparing Email" Fcc: Sent MIME-Version: 1.0 To: git@vger.kernel.org Cc: Emily Shaffer , Johannes Schindelin , Victoria Dye , Eric Sunshine , Philippe Blain , Philippe Blain , Philippe Blain Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org From: Philippe Blain From: Philippe Blain The previous commit added a standalone section on the purpose of the cover letter, drawing inspiration from the existing content of the "Preparing Email" section. Adjust "Preparing Email" to reference "The cover letter", to avoid content duplication. Also, use the imperative mode for the cover letter subject, as is done in "The cover letter". Signed-off-by: Philippe Blain --- Documentation/MyFirstContribution.txt | 38 +++++++-------------------- 1 file changed, 9 insertions(+), 29 deletions(-) diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt index de62a61771c..078b96d674a 100644 --- a/Documentation/MyFirstContribution.txt +++ b/Documentation/MyFirstContribution.txt @@ -1040,46 +1040,26 @@ directory you specified - you're nearly ready to send out your review! [[preparing-cover-letter]] === Preparing Email -In addition to an email per patch, the Git community also expects your patches -to come with a cover letter, typically with a subject line [PATCH 0/x] (where -x is the number of patches you're sending). Since you invoked `format-patch` -with `--cover-letter`, you've already got a template ready. Open it up in your -favorite editor. +Since you invoked `format-patch` with `--cover-letter`, you've already got a +cover letter template ready. Open it up in your favorite editor. You should see a number of headers present already. Check that your `From:` -header is correct. Then modify your `Subject:` to something which succinctly -covers the purpose of your entire topic branch, for example: +header is correct. Then modify your `Subject:` (see <> for +how to choose good title for your patch series): ---- -Subject: [PATCH 0/7] adding the 'psuh' command +Subject: [PATCH 0/7] Add the 'psuh' command ---- Make sure you retain the ``[PATCH 0/X]'' part; that's what indicates to the Git -community that this email is the beginning of a review, and many reviewers -filter their email for this type of flag. +community that this email is the beginning of a patch series, and many +reviewers filter their email for this type of flag. You'll need to add some extra parameters when you invoke `git send-email` to add the cover letter. -Next you'll have to fill out the body of your cover letter. This is an important -component of change submission as it explains to the community from a high level -what you're trying to do, and why, in a way that's more apparent than just -looking at your diff. Be sure to explain anything your diff doesn't make clear -on its own. - -Here's an example body for `psuh`: - ----- -Our internal metrics indicate widespread interest in the command -git-psuh - that is, many users are trying to use it, but finding it is -unavailable, using some unknown workaround instead. - -The following handful of patches add the psuh command and implement some -handy features on top of it. - -This patchset is part of the MyFirstContribution tutorial and should not -be merged. ----- +Next you'll have to fill out the body of your cover letter. Again, see +<> for what content to include. The template created by `git format-patch --cover-letter` includes a diffstat. This gives reviewers a summary of what they're in for when reviewing your topic. From patchwork Wed May 11 01:47:33 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Philippe Blain X-Patchwork-Id: 12845687 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id EF332C433EF for ; Wed, 11 May 2022 01:48:08 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S240705AbiEKBsF (ORCPT ); Tue, 10 May 2022 21:48:05 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:45480 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S236703AbiEKBrr (ORCPT ); Tue, 10 May 2022 21:47:47 -0400 Received: from mail-wm1-x32d.google.com (mail-wm1-x32d.google.com [IPv6:2a00:1450:4864:20::32d]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 86EF52228A for ; Tue, 10 May 2022 18:47:46 -0700 (PDT) Received: by mail-wm1-x32d.google.com with SMTP id l38-20020a05600c1d2600b00395b809dfbaso110444wms.2 for ; Tue, 10 May 2022 18:47:46 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=message-id:in-reply-to:references:from:date:subject:fcc :content-transfer-encoding:mime-version:to:cc; bh=oC9Wo4de6FMpWWlSzFLzca9U6ibPw5mGjGc5kHvqGS4=; b=PIMOIZOkiImtgSfO5MdrLbToiNeKRY1pO6jibGmfQS4+ebLAq3sEgi5dwf5MPc3JhI bfPH7YF60tfPnvPDUgxFWEUEBK322ja4wvTUa4G1i0tYmORKizq/yZoTfGqVXmDpfDjy 6yP37mN3favhDhxGTJnX8Iu0ekohsF1TCmMhrKUWqH/ouiJkMLUP1vgV2nr/BdrkOv3k UaFLgVwJeZVTsq4YRNM8E1PwJALnRvgIR9sKnopsikc5BUfmM0bqJWEWlrB5azIHE5Fz u6PKf0UUsKLYAZ1LDGqvaBmvNmLTX0E0N9lwKCebj1W+KlCClk+ngVISW2/Kt5K/Basu J/Yg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:message-id:in-reply-to:references:from:date :subject:fcc:content-transfer-encoding:mime-version:to:cc; bh=oC9Wo4de6FMpWWlSzFLzca9U6ibPw5mGjGc5kHvqGS4=; b=Goz6aQv9zAOtQn4sm/JcYQnVDs3G1axEsFsr1/mr0rf3VpR0Yv3kv9TPl2FOX9xWbx fVTGEuCwwJBfEd5yH2oB28WWK9FaWTTphM5M0zvlJ2qpy2ZBHF8rDTtWsQyrBVJbSI5h Wz03A9OrKTur4ylh5FO9e+DUi0yzJsE5PBi3blr6E/VbWeRzCLC1hNbrn0MFrlwmzftj ZletRJ+1ECJX4ibOZ36485RA+IV8rgEvPKOkVySZuM5ZGyJ0GNrbq/W8j0tgcbyjFfLU +hM0WKh6gav9ZtF32J1IU4uhaOM0dttnrGsUVDj+G9wDBET/Ns1my2/B9ysfefYHPKnJ tb7g== X-Gm-Message-State: AOAM532RXtBAREWqGJapwC9VX044A/yfCzlBfWrgHXOtiYySK30fUgta zCBFg0kbMKR/YY+kPHP9UUBj76vr0/c= X-Google-Smtp-Source: ABdhPJy53LidrSHbfCMMknKYCcnvuMIujZR0+AubxjdGKTfqkoxRZfZvk33L2yaxbeJBiZfriTfddw== X-Received: by 2002:a1c:770b:0:b0:394:3fae:ab79 with SMTP id t11-20020a1c770b000000b003943faeab79mr2390105wmi.200.1652233664850; Tue, 10 May 2022 18:47:44 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id l15-20020a1ced0f000000b003942a244ecbsm697367wmh.16.2022.05.10.18.47.43 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 10 May 2022 18:47:43 -0700 (PDT) Message-Id: In-Reply-To: References: Date: Wed, 11 May 2022 01:47:33 +0000 Subject: [PATCH v2 4/5] MyFirstContribution: reference "The cover letter" in GitGitGadget section Fcc: Sent MIME-Version: 1.0 To: git@vger.kernel.org Cc: Emily Shaffer , Johannes Schindelin , Victoria Dye , Eric Sunshine , Philippe Blain , Philippe Blain , Philippe Blain Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org From: Philippe Blain From: Philippe Blain The "Sending Patches via GitGitGadget" section mentions that the PR title and description will be used as the cover letter, but does not explain what is a cover letter or what should be included in it. Refer readers to the new "The cover letter" section added in a previous commit. Signed-off-by: Philippe Blain --- Documentation/MyFirstContribution.txt | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt index 078b96d674a..728dc437854 100644 --- a/Documentation/MyFirstContribution.txt +++ b/Documentation/MyFirstContribution.txt @@ -893,8 +893,12 @@ https://github.com/gitgitgadget/git and open a PR either with the "New pull request" button or the convenient "Compare & pull request" button that may appear with the name of your newly pushed branch. -Review the PR's title and description, as it's used by GitGitGadget as the cover -letter for your change. When you're happy, submit your pull request. +Review the PR's title and description, as they're used by GitGitGadget +respectively as the subject and body of the cover letter for your change. Refer +to <> above for advice on how to title your +submission and what content to include in the description. + +When you're happy, submit your pull request. [[run-ci-ggg]] === Running CI and Getting Ready to Send From patchwork Wed May 11 01:47:34 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Philippe Blain X-Patchwork-Id: 12845686 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 60853C433F5 for ; Wed, 11 May 2022 01:48:03 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S238791AbiEKBsB (ORCPT ); Tue, 10 May 2022 21:48:01 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:45636 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S240658AbiEKBrt (ORCPT ); Tue, 10 May 2022 21:47:49 -0400 Received: from mail-wm1-x333.google.com (mail-wm1-x333.google.com [IPv6:2a00:1450:4864:20::333]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 4D56A1DA7F for ; Tue, 10 May 2022 18:47:48 -0700 (PDT) Received: by mail-wm1-x333.google.com with SMTP id c190-20020a1c35c7000000b0038e37907b5bso2336765wma.0 for ; Tue, 10 May 2022 18:47:48 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=message-id:in-reply-to:references:from:date:subject:fcc :content-transfer-encoding:mime-version:to:cc; bh=KMXOk1tvSHhYsPdV9+MPOTx+EM/dzssS8wUUh7sT8ew=; b=ZPiREeRZJRm/eY9k7aGe0U7KNwB0MyArtBWabiKww3odWv9rbyQ5rGSOImoIP0EHN5 AzpXGyH0VW+Yni/YCA69pF8Pz+auvO2wMvZBMePqYxKC0tfOXLMP9XiTvcsY8NwWytqL sz2L5RzrkEkjnrSr3kAsMm8QYl5OmlKdJ1e+ECsrmD5fG8OY+tZBF5pZAcYCncX6l9lR Vmff/q7OFK4Mbra9gipLuPBZWCS66V4+J3KnYy/VDMG0CsgXaPogx3Iyf9Lq+RcfZlzP pih/aBXhuE9OEGyohnRmXE0x1Ccf0hH+2q4OGrhlI9GF7Y7TelJbs0BLF2/dLLf5RLKk BvSw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:message-id:in-reply-to:references:from:date :subject:fcc:content-transfer-encoding:mime-version:to:cc; bh=KMXOk1tvSHhYsPdV9+MPOTx+EM/dzssS8wUUh7sT8ew=; b=AABzh5yfDhEnpWfSNiLzG2ZlMK2+yp7lYjEku3iE0mB0MMXSuIehLCNNCdN91u8U2h CQ7gPJo07LUwhfr/TCrcSQ9UR0O+AWjgCd8GSTpvwibxsl4H9vA/hA1aoKay1NDmMWms 5liEkKtxybiCs2XG2mE56TrMAipLktpkwql047C+umLTTA/R5WaLE0xJffHk2Lrg6sVZ YNGyhuJJWmatp8KN819mM8rH5LqGoZc5qvAQlGfOpZJHr7fKlraKGz8p1r8WSZURbUX7 BSJ9/x03Y0kXINXXseCsZR+qpY1npfw2iR4ANBZGGyV1oaiXIPeV5P7gb8Ztk1/gciUp L+KA== X-Gm-Message-State: AOAM533iRPaQ+VyIn0bDO00Z4le/TqW2x4KT23lM8JPOnVQBEjKZUGs+ wPbu64p69fXM1iq4AJkHlhxFkp2v2u4= X-Google-Smtp-Source: ABdhPJwp0HBmO2TSUL7fGChrjn7JS52zOJ+tcPjy32+6kbdje4I0cVtn1XgZSXhTvcudBmWpXlBG6g== X-Received: by 2002:a05:600c:21c8:b0:394:7796:49c0 with SMTP id x8-20020a05600c21c800b00394779649c0mr2453587wmj.191.1652233666642; Tue, 10 May 2022 18:47:46 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id a19-20020a05600c349300b003942a244f2bsm4222648wmq.4.2022.05.10.18.47.45 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 10 May 2022 18:47:45 -0700 (PDT) Message-Id: <33256c6b4bafe2a3993338a7499dfec52a02a9a0.1652233654.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Wed, 11 May 2022 01:47:34 +0000 Subject: [PATCH v2 5/5] MyFirstContribution: drop PR description for GGG single-patch contributions Fcc: Sent MIME-Version: 1.0 To: git@vger.kernel.org Cc: Emily Shaffer , Johannes Schindelin , Victoria Dye , Eric Sunshine , Philippe Blain , Philippe Blain , Philippe Blain Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org From: Philippe Blain From: Philippe Blain By default, GitHub prefills the PR description using the commit message for single-commit PRs. This results in a duplicate commit message below the three-dash line if the contributor does not empty out the PR description before submitting, which adds noise for reviewers. Add a note to that effect in MyFirstContribution.txt. This partly addresses: https://github.com/gitgitgadget/gitgitgadget/issues/340 Signed-off-by: Philippe Blain --- Documentation/MyFirstContribution.txt | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt index 728dc437854..01b9e5db117 100644 --- a/Documentation/MyFirstContribution.txt +++ b/Documentation/MyFirstContribution.txt @@ -898,6 +898,16 @@ respectively as the subject and body of the cover letter for your change. Refer to <> above for advice on how to title your submission and what content to include in the description. +NOTE: For single-patch contributions, your commit message should already be +meaningful and explain at a high level the purpose (what is happening and why) +of your patch, so you usually do not need any additional context. In that case, +remove the PR description that GitHub automatically generates from your commit +message (your PR description should be empty). If you do need to supply even +more context, you can do so in that space and it will be appended to the email +that GitGitGadget will send, between the three-dash line and the diffstat +(see <> for how this looks once +submitted). + When you're happy, submit your pull request. [[run-ci-ggg]]