From patchwork Thu May 12 23:43:33 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Philippe Blain X-Patchwork-Id: 12848226 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 862E1C433EF for ; Thu, 12 May 2022 23:43:55 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1359597AbiELXnw (ORCPT ); Thu, 12 May 2022 19:43:52 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:44704 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1359596AbiELXnq (ORCPT ); Thu, 12 May 2022 19:43:46 -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 91AFC289BD6 for ; Thu, 12 May 2022 16:43:41 -0700 (PDT) Received: by mail-wr1-x434.google.com with SMTP id f2so2251829wrc.0 for ; Thu, 12 May 2022 16:43: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=B02hhJ+DIIN3W7Lil8FGBtfUqz5Zpaqs+7HSK8Gt1bQPyYvaBZdSBJIjLILfnCtckX uJiN3VA24D2CqcPYxbbEBrMN5oFeBD86rsmtLL4gloyTuvqYfAckHH7y9oV+S9s1W40d ebbgVfhzvLPuLoDRAnBPfciXylBdkwo36N248nAKFdyKYGaom3n9foMSd3kHIpRBvsYs 9QjibwkqF6n7hHjyW9T0FaKO6lw0q228HDmfjQWt6qBckZc14xA9nD1+uyW1nddZ8pE2 4xMCMASzn7afJhHgCAbo7OIJ3pf95e5Z8kVGaR3enKPSmx0Vkc2dFbEM99d6LZ9etfJb eXgQ== 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=KaGrsQMElIhuhu6uUKAIqOjUolHMxRdiNlY0yIPzD2mdATIfk4gZ/y5iwBPuTQ1SA4 ebrV4qV/3/sM9ulcLXbC8aZ99J6XDBdYeDFOcYjiGCdzPg8rbKWl3Jiagozm0FimSoeD wIAvo62fXzdwUDtB/fE+kaYK7CXoFpVm6VkSGvoiTZVLekCCyQLVW8btNUsaYb1+o0oD eAA5eJgIMzYA4Rw7PSCgeI0u8sBRL91dJcYqs1vDgf+V3XRz8Tug/hcumjUoOmRLk26o 3l4pBUNCVuvryAsh9zfKkliPGHJpfHPxnl22UqKwn3mY3+ybFhbo4dzHybH4N0MheZ8C dpcg== X-Gm-Message-State: AOAM530BcAF0scl7P8S6opjwtZRzpfoghZvJdZcILaajBYJw32eBP/fM PePO2iOqymZWY8ce04rx2X1BasaUa08= X-Google-Smtp-Source: ABdhPJyv00HkHMwlxfeKRhWTZb1O4PBHU8Bdr2qdzL2qa5jzbV/D2vmnuYr8OltVibzjBbfbjzbzqQ== X-Received: by 2002:a5d:4052:0:b0:20a:d8b9:9d4b with SMTP id w18-20020a5d4052000000b0020ad8b99d4bmr1600358wrp.612.1652399019730; Thu, 12 May 2022 16:43:39 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id p2-20020adfaa02000000b0020cd0762f37sm638460wrd.107.2022.05.12.16.43.38 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 12 May 2022 16:43:39 -0700 (PDT) Message-Id: <59af7e5e5ad84103b39ac9511791eb06b88df3c6.1652399017.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Thu, 12 May 2022 23:43:33 +0000 Subject: [PATCH v3 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 , Bagas Sanjaya , Philip Oakley , 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 Thu May 12 23:43: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: 12848229 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 7EE6AC433FE for ; Thu, 12 May 2022 23:44:01 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1359622AbiELXoA (ORCPT ); Thu, 12 May 2022 19:44:00 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:44688 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1359595AbiELXnq (ORCPT ); Thu, 12 May 2022 19:43:46 -0400 Received: from mail-wr1-x429.google.com (mail-wr1-x429.google.com [IPv6:2a00:1450:4864:20::429]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id C91F4289BE0 for ; Thu, 12 May 2022 16:43:42 -0700 (PDT) Received: by mail-wr1-x429.google.com with SMTP id b19so9235566wrh.11 for ; Thu, 12 May 2022 16:43: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=hL6JSLdjVbdVjD5T2UlHRtSJRkuLVyPAPM4zlPDnOU8=; b=Qy1KK7CpC1JrQFinywOg1Agz77DzEOut6PiE8+iDYaBofWwWG8j3/1p2xuCZfBOTIo 7JAyZHAKGIZ3uNQ1NBUnEBw/x5Yi3Q8i1DWQCEdM1XXt3XHIyEVbjzgTg1AVhby23AfR pqtbgfGuZ0fv5Z51LfMqmAyHNP1NlRxGfyhhyiHlRfHhf6bhtrQTRkV+pCZAkuhYAed+ RJZ8qryQO0PBlXwFNT4MI2XXJhVTaFbUv5wlQ53QSxgZPPSh+3bgFkc5RGerakSoiouN P8Raju2A56TE0YeIiaO5IZztmnI0PYa6qkqX+uxgjhaTZiTYn2RDSdAmahH7PFD8RNQd ci1w== 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=hL6JSLdjVbdVjD5T2UlHRtSJRkuLVyPAPM4zlPDnOU8=; b=7yl5I/HvaVMX1QR5dbX7N4O+8CHPyGTNAsfYqx8GaBBW/hz7wO5ioBKGkOya8lsIIz mfTPMsWw5L9W3LSbKzHgqYC2eU/qEefVMDThsgbEtHjesXB4xGjvW9JV52bJoJBlA/N7 5iOG6DxWOy39DHlec9z1mbT9ZUTd6ANPGRvc+EztErtbkTIbqS+vaLbWzouhKWGWZb6H 9jq0efoeJjhCAM/xoRuJ6pKN451l7/3kO16co3jf2RxeX2JuZevwR2RGjGt7K574yeF8 v5byl9m5C7hZxLTje8BkZIEznGRvh11r7F3Nx5WCw9l0TL0IjdjJE5L/XC9flW5/GuUn iqSQ== X-Gm-Message-State: AOAM530NP8GImdoy7j6P0/VrxYQCzyVBCkKRCr5LNSSErBmzlu+yjhaw vMBBWL2fZz4yIflZnKUpf29UsCt+Z3o= X-Google-Smtp-Source: ABdhPJy/JmK4c/mITGdNO9bnU6OYwF7qIH1k1pXGu4RcGn4AgK0wX3rnyYGSJPQao3HMWu7j9Nkhmw== X-Received: by 2002:a5d:47cc:0:b0:20c:6b7c:8a19 with SMTP id o12-20020a5d47cc000000b0020c6b7c8a19mr1552009wrc.608.1652399020952; Thu, 12 May 2022 16:43:40 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id l9-20020adfc789000000b0020cd8f1d25csm753195wrg.8.2022.05.12.16.43.40 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 12 May 2022 16:43:40 -0700 (PDT) Message-Id: In-Reply-To: References: Date: Thu, 12 May 2022 23:43:34 +0000 Subject: [PATCH v3 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 , Bagas Sanjaya , Philip Oakley , 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 | 51 ++++++++++++++++++++++++--- 1 file changed, 47 insertions(+), 4 deletions(-) diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt index 22848f84bec..94f722d4b7f 100644 --- a/Documentation/MyFirstContribution.txt +++ b/Documentation/MyFirstContribution.txt @@ -760,9 +760,52 @@ We can note a few things: _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). +- Subsequent iterations of the patch series are labelled "PATCH v2", "PATCH + v3", etc. in place of "PATCH". For example, "[PATCH v2 1/3]" would be the first of + three patches in the second iteration. Each iteration is sent with a new cover + letter (like "[PATCH v2 0/3]" above), itself a reply to the cover letter of the + previous iteration (more on that below). + +NOTE: A single-patch topic is sent with "[PATCH]", "[PATCH v2]", etc. without +_i_/_n_ numbering (in the above thread overview, no single-patch topic appears, +though). + +[[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 also be in your commit messages. + +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 +1043,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 Thu May 12 23:43:35 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Philippe Blain X-Patchwork-Id: 12848225 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 C6544C433EF for ; Thu, 12 May 2022 23:43:51 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1359594AbiELXnu (ORCPT ); Thu, 12 May 2022 19:43:50 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:44716 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1359603AbiELXnr (ORCPT ); Thu, 12 May 2022 19:43:47 -0400 Received: from mail-wr1-x432.google.com (mail-wr1-x432.google.com [IPv6:2a00:1450:4864:20::432]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id BDD4B289BF1 for ; Thu, 12 May 2022 16:43:43 -0700 (PDT) Received: by mail-wr1-x432.google.com with SMTP id d5so9273223wrb.6 for ; Thu, 12 May 2022 16:43:43 -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=omZd82WqRODSZdAJWA5SF/bc9gSX6LVfdB5B/V4bIXw=; b=AZXDgGuP1gd0IzKHKlizcyGJo3yBMHh/jSb1AEVIkkGFt+e2S09gd91Idf8K6Xsp0d 3R5kuRX6EjqRwyrFn5APxY9+hqI9+b56A8lg1jYtsMyI21L1jK0M5/3Oz3aIVrSvI2BL Kc8ra90xO+EvJNYt38QBlZb6PNK7ZLdOXSwC9kY5xzDiap8P+z5VVGSYdXitx9nyPKcD C83oy7vjqchffM0ySiYRCiYOU5cXDIemCjD7cvKqhrV946FiRWys49O5nJZF3gtbUnmW XD2fTSLXWz3wlmobrxT3/gQz9jlc4lONAisD2btdnDk+VzZD7HIELHjYgifBSEbJpFiC YCuA== 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=omZd82WqRODSZdAJWA5SF/bc9gSX6LVfdB5B/V4bIXw=; b=aHG02mnZi61h2XSY4Fsjatz0SlSLdn6plGT7k49mjmz3iejFD9+wXdo03IkBM1sJoY ZpnOImCrZWluGRX1cbukBxQLwSITnMcEZ2A0aDor/6EeHFa3oKm+e1JgKUYO/RX/6cTS CUywl0WNwJLGah6pAQYbz/l70VvLM3wGpPAq2+0mnCoKYikQeEfJStbh7mA8+wSrCePS xkDAD3YZUiFk9ZLDTgq576iocRwiWsybHqNZYAA6zP4GDTSxWCEKJMUPOsmBSd5kZ+PE kJGjEv2K7qWWkYMo0AMUnHkR+Lu0w7HQgj5WL1mxN2wyoDNL/jtv6mj3pu/QiGwPJ6Uz vE8Q== X-Gm-Message-State: AOAM5301zOy90O+7Rlc0hckyIWo6MgOjUA0PcjoSBced5cqgqurjaA0y ZS+DQRJTXtTGv+++mNUrgciczNZwmlc= X-Google-Smtp-Source: ABdhPJyvG81jHgovpb+7YLeuHutpZ8VAURAJ6nzm6dbuOqVDssPVcIX1ll5KZ0EoWPI5dRvu71Or6Q== X-Received: by 2002:a05:6000:1786:b0:20c:6063:5014 with SMTP id e6-20020a056000178600b0020c60635014mr1620090wrg.251.1652399021994; Thu, 12 May 2022 16:43:41 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id az31-20020a05600c601f00b003944821105esm881969wmb.2.2022.05.12.16.43.41 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 12 May 2022 16:43:41 -0700 (PDT) Message-Id: <2caec6e619a89e9e10399da0feb04fa0a21b15a4.1652399017.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Thu, 12 May 2022 23:43:35 +0000 Subject: [PATCH v3 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 , Bagas Sanjaya , Philip Oakley , 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 94f722d4b7f..f6ee5b8b1ae 100644 --- a/Documentation/MyFirstContribution.txt +++ b/Documentation/MyFirstContribution.txt @@ -1046,46 +1046,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 Thu May 12 23:43:36 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Philippe Blain X-Patchwork-Id: 12848228 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 E41B6C43217 for ; Thu, 12 May 2022 23:43:59 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1359617AbiELXn5 (ORCPT ); Thu, 12 May 2022 19:43:57 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:44722 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1359604AbiELXnr (ORCPT ); Thu, 12 May 2022 19:43: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 185C6289BFF for ; Thu, 12 May 2022 16:43:44 -0700 (PDT) Received: by mail-wm1-x32d.google.com with SMTP id 129so3909676wmz.0 for ; Thu, 12 May 2022 16:43: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=eJhSanNTrvwh73K6ul8u5rLauB4yVfCuB5NCOfi1PhE=; b=oQH1i16nWhsiWLP3qbER5hZpkF3wkIwh679YuaHYua9NH7Q0YszEXA346eMi0p03SO XeLO+vimm6hl1ug3wWnlSwFcf/llbIr7t+6ZXieCuejh9NBdn/DZwm5JiBbc7y+Y2k/t SThUUQGcf6pRDm1ciB80jgHbQ1F2fe9ZZB+JfBQ/UK8rd9kBIziAkLxlSTSrzTmhZcFe AXydGSUWR++FvybLpdDsNhlY/id+9nZFLYr+gC5/5+IBpxxjFG0fXUpO9YX4CJhckm+v FcoWUAp2L1TsCZiZ02zzKUbsIJZJJISWveS/h/IzoW8e/WhFJ1OqFBl9UQ6zxW+urEWp dKqw== 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=eJhSanNTrvwh73K6ul8u5rLauB4yVfCuB5NCOfi1PhE=; b=scN8p+yfkmBLY/iUnESSJtI3QUZNBPxvwf9Va4NrlrQJ3QCrKj3lYpYAKFMfB/JdZh kv3MGJHIGAcI+ifwTw1Osz9+NBFv5GONIUNoDP9HX5tBYB76lTeHlWU9p8EnaNoE3cXe PCFSnLb/iiaNOaUf/3dlUsvuVZHl9wkySm8LYpZuG79le3HVkTxbj41vW9S4eeRkoRSY OGMWndb2b9X8DBEgGDEc3G3JATj3ANWKqQ8tIhbmhyqrdzVangK2z8AlO7oaT//Slro0 nPuqsH7pdmxX8qwGuhkA8GV8z/7SzDV6b9Lxungo7jyC9ZaNtc2lbCZbvlaQ9D8k5A8l svzg== X-Gm-Message-State: AOAM530orCnxhsYYbde4ULinnNCmBRYDvZnLAdnym7f3bFI+/TUgPW0H 6kqjO6efiSKLATnLdFq/oNDKcSkvHG0= X-Google-Smtp-Source: ABdhPJwcWHeXhroPS8jJATNj+nj/psfaCiJhdirpt61Q2poVz/n2upMg602uvzDVU+N1Mhr+TPC+pw== X-Received: by 2002:a7b:c5d0:0:b0:389:fe85:3d79 with SMTP id n16-20020a7bc5d0000000b00389fe853d79mr12457140wmk.77.1652399023151; Thu, 12 May 2022 16:43:43 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id a4-20020a05600c348400b003942a244ec4sm861965wmq.9.2022.05.12.16.43.42 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 12 May 2022 16:43:42 -0700 (PDT) Message-Id: <02598d431e0eb4f7cad9b7703c2fb244c3d15781.1652399017.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Thu, 12 May 2022 23:43:36 +0000 Subject: [PATCH v3 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 , Bagas Sanjaya , Philip Oakley , 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 f6ee5b8b1ae..9eb2dfec959 100644 --- a/Documentation/MyFirstContribution.txt +++ b/Documentation/MyFirstContribution.txt @@ -899,8 +899,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 Thu May 12 23:43:37 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Philippe Blain X-Patchwork-Id: 12848227 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 8C326C433F5 for ; Thu, 12 May 2022 23:43:56 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1359605AbiELXnz (ORCPT ); Thu, 12 May 2022 19:43:55 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:44744 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1359607AbiELXnr (ORCPT ); Thu, 12 May 2022 19:43:47 -0400 Received: from mail-wm1-x32a.google.com (mail-wm1-x32a.google.com [IPv6:2a00:1450:4864:20::32a]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 2914E28AB8E for ; Thu, 12 May 2022 16:43:46 -0700 (PDT) Received: by mail-wm1-x32a.google.com with SMTP id k126-20020a1ca184000000b003943fd07180so3856314wme.3 for ; Thu, 12 May 2022 16:43: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=s6mAAFAjova36jeVuNp1f4ouBVDKYHmolLXPxF09+Eg=; b=KHSbg9nSSSdE/uFkBbMVzydw7nqbkMehJwO7HVYRD5UEeLLtUgaOMExm9edxLC+oV4 fjB2qc2UVFVHTJcUXOIZIjKABtIP7dyf/ErbbXcaK6B0B3JiXlnHWI3eoSbG/xxYdOvB Rr3c9YmzqePggkbdz/N3EuIa5CcPn4x0P6zTv0JaTDDtx0uMyU3yH+8moEp77KNkUk4p +lg6IaV+iIGblyRTP1Y9BLZL8fMeNajLIP+suriXEEYZOUcf+f+qiS2J4LYQS6at38Tf XD1k5iV1YbJ6Y2ZcfLDgAXG2/atpsnbAyHZAjoZ3iVvUbVxgVKBIKT1KGBRoPQDJlaB5 fYCg== 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=s6mAAFAjova36jeVuNp1f4ouBVDKYHmolLXPxF09+Eg=; b=xv8Zg6Od3ZzUgXgbBgNCczvLw6G1KFS3qMojSL1oMudwCnjE6hGjnRTPjTY+Qu1Chv FDKl5lqxPN6XMWVO3bOCQkbyQ+o4+ggyYnpFD4zg/VHnyMpupIfXnlvJH9RVbXvxLdgq twNvjQ1slA/XvQRLQ6Tf018Qag2e2Zy7Drj/powbIVHQSOfgNvs5sJWMch7esSzFRHew KXECBhuUBVY/O2s17hxafpsF1YqVV78IjlDI9JW07KLzKO1C0V8mU9yqiD3jWHCSoYiV yDVw6U1E3DseaD54wm63mg6cl8PhLyYAtjFLfmR9crk5gabzLrnWyIU9wi5LX2wJUSY2 W3ig== X-Gm-Message-State: AOAM530VLlzrxPFjmlBIVeN1Xsx8g5f9uRiimdgLAM2301nErvYZJda+ iM3CrtkMdQYIOVU+v8VpkeYYYwMLxxw= X-Google-Smtp-Source: ABdhPJzYVhEXMdUyCWb8PsRYDyZ1Tx+F8hoGo31gSNoLobCK1Mj8aw/Qo5SRm87kbgktsQN+hRu8fA== X-Received: by 2002:a05:600c:1d18:b0:394:6469:abec with SMTP id l24-20020a05600c1d1800b003946469abecmr1914000wms.89.1652399024226; Thu, 12 May 2022 16:43:44 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id j32-20020a05600c1c2000b00394832af31csm4236051wms.0.2022.05.12.16.43.43 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 12 May 2022 16:43:43 -0700 (PDT) Message-Id: <76bcb6612e40aa3d5244658f9ff90f453222836a.1652399017.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Thu, 12 May 2022 23:43:37 +0000 Subject: [PATCH v3 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 , Bagas Sanjaya , Philip Oakley , 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 9eb2dfec959..1da15d9ad44 100644 --- a/Documentation/MyFirstContribution.txt +++ b/Documentation/MyFirstContribution.txt @@ -904,6 +904,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]]