From patchwork Wed Apr 27 19:04:46 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Philippe Blain X-Patchwork-Id: 12829378 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 B11ACC433EF for ; Wed, 27 Apr 2022 19:13:00 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232790AbiD0TQJ (ORCPT ); Wed, 27 Apr 2022 15:16:09 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:60378 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S234082AbiD0TOL (ORCPT ); Wed, 27 Apr 2022 15:14:11 -0400 Received: from mail-wr1-x435.google.com (mail-wr1-x435.google.com [IPv6:2a00:1450:4864:20::435]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 7FC4B8F1B4 for ; Wed, 27 Apr 2022 12:04:54 -0700 (PDT) Received: by mail-wr1-x435.google.com with SMTP id v12so3766008wrv.10 for ; Wed, 27 Apr 2022 12:04:54 -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=qMzPqCYiUBQQGIgQIGR8vgq8/L7GJ52bPFf1vWQ6S00=; b=aEEUy2X30AvwjCJol4UVO8G2qeSullXzjREJCBKumHUS1+dBTOYLPbPrBuk3dxz2nE Otn4ivLI5zoDIIfHYFGbBBDupR01luT8hT5GaRiUEgWhuwELaW1F3D5sE+GpaQR0jhQP Qk8Xsc/5HQNWK3YfGOxUbaL6p/H0hEbjMStEdmfJvd9WjS2nzmvZWRkwpoPSkXe8Cqet P2VkvVW8cvAdPFLfbeP61Dif0pV2lD6bs0QJP2qL4bGqW6rJxWdN6gf89otigrnrsQJJ jn92uLBvBBHFJq7d7KA9yCUb4gYxqLD+hjB3JWL7ptL7aYzwD3Cv7s+MwdO+9x66hot2 3tTQ== 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=qMzPqCYiUBQQGIgQIGR8vgq8/L7GJ52bPFf1vWQ6S00=; b=xivxFa3u+uRpdGDy5jv7q3Bl15lNeI/gfResAVExV4MSbTNcAoE7VsAZnrCWszPknL U7xJK1IPb1NOipAsTTSTDpsnX7Ew3lzxPGJkwLvsRfmnZJIvb/dtfePQez4H3hUG0lgP bP93J9PtuRNFo67Z95gHQuaUYtOpfRBNd92Xc9zT+oZASGft39LFRlflDwKGzCekHH0+ Hv9TJWFo3Nwav3gXluHSRfgXbwOy0nfTpM1/5ZQrmF5CqOJFb8NdBeV0CG3ptnGlneNX NIjyL7yXXYhK6yQA4lTrPbDOA0NEq88UYXsghr7xFHwVMNrTLP31pzk9QxINjJUdVinN L9/g== X-Gm-Message-State: AOAM530O++xik4HE+bax7DtxAV0hUCv0oLL7NeP74P76+z7OJFmZ9Yn2 eg7Zu009yZaMGHsWYARKk1jjj9DVVBo= X-Google-Smtp-Source: ABdhPJwrJHhchEZ5Iste1DWfNHxfw4Dp5++Q+FWm81NgTSoc8BPQS5uSlAQ3qv44FpJCBNajhQg5BA== X-Received: by 2002:a5d:6d50:0:b0:207:c10e:911 with SMTP id k16-20020a5d6d50000000b00207c10e0911mr23730104wri.137.1651086292553; Wed, 27 Apr 2022 12:04:52 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id r10-20020a7bc08a000000b0039049f8b3f9sm2110742wmh.27.2022.04.27.12.04.51 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 27 Apr 2022 12:04:51 -0700 (PDT) Message-Id: <7e84d5b286de9dddf28ef1c8f38c7d7c28e266f0.1651086288.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Wed, 27 Apr 2022 19:04:46 +0000 Subject: [PATCH 1/3] MyFirstContribution: move cover letter description to a separate file Fcc: Sent MIME-Version: 1.0 To: git@vger.kernel.org Cc: Emily Shaffer , Johannes Schindelin , Philippe Blain , Philippe Blain Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org From: Philippe Blain From: Philippe Blain In a subsequent commit we want to reuse the explanation of the purpose of The cover letter form the "Sending Patches with git send-email" section in the "Sending Patches via GitGitGadget" section. To avoid text duplication, move this explanation to a separate file and include it in MyFirstContribution.txt. Signed-off-by: Philippe Blain --- .../MyFirstContribution-coverletter.txt | 18 ++++++++++++++++ Documentation/MyFirstContribution.txt | 21 ++----------------- 2 files changed, 20 insertions(+), 19 deletions(-) create mode 100644 Documentation/MyFirstContribution-coverletter.txt diff --git a/Documentation/MyFirstContribution-coverletter.txt b/Documentation/MyFirstContribution-coverletter.txt new file mode 100644 index 00000000000..b9e1e10427a --- /dev/null +++ b/Documentation/MyFirstContribution-coverletter.txt @@ -0,0 +1,18 @@ +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. +---- diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt index 63a2ef54493..681bbefe9cd 100644 --- a/Documentation/MyFirstContribution.txt +++ b/Documentation/MyFirstContribution.txt @@ -976,25 +976,8 @@ 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. +include::MyFirstContribution-coverletter.txt[] 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 Apr 27 19:04:47 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Philippe Blain X-Patchwork-Id: 12829377 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 50C89C433EF for ; Wed, 27 Apr 2022 19:12:58 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231523AbiD0TQI (ORCPT ); Wed, 27 Apr 2022 15:16:08 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:60958 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S234122AbiD0TOL (ORCPT ); Wed, 27 Apr 2022 15:14:11 -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 CF7AA8FFA4 for ; Wed, 27 Apr 2022 12:04:55 -0700 (PDT) Received: by mail-wm1-x335.google.com with SMTP id u9-20020a05600c00c900b00393e729e655so1802109wmm.0 for ; Wed, 27 Apr 2022 12:04:55 -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=uNuRHtJSQus1+6Fh1noMDel6zMOZVB1tWfGtU/0QLbg=; b=CQM1UPp2IWAd5oMOlKkNsh3vELfdq/u8bvpKvQi9OLfAWWiA0yR/fSsmyD+FHFwWDt bq7lwhy/y/w3rj1/QNTaKUw2LhzKmb2f2vdioqSXxzk0ihwt25Epgsl8WFsTLSMrXmLo vXMFlzLVl2qfgpHfRGco9P5MmpdfVuaquWpmCzuOtNQGn0PTEmj1lfsDH3h62u6dqbW2 KbsUf7vpYObdyltZXkbqi7bjc+/S+KTaCctjgLlg5pumIze5SMKHg8/RH6lZKRxRmwbv S0dwEIxG/QNwXWgQ4iC7c4L4ibjTkIUO+t7h7hv7O8mqeB9nZDsQW5pxt+aOdqmyZ9G7 AwPA== 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=uNuRHtJSQus1+6Fh1noMDel6zMOZVB1tWfGtU/0QLbg=; b=XoN3Ey5dj7NrGtaINohYSFvBsRGmttIVWM9r7cVR2hY/r1CHLMBTOTeQq5w3K/zEn0 BJm4XBnvGeDdavkwp2kE0xmCvvE45P1jIqbMfJ6Ce3CmwSKqiSEIM2Ji8pVEsc43pIxh JaFifJur5VgL6Cg9b6qMbsP38zQKcdU74Zs7eOuHOAaQNORnQu5nGrOhH6svkgzC9372 lNXyXAqyrtGY6kJXGwGQVFjuDXros+3piMVlOOHCu0NcP/VkjiVZYANyrlOpVyhPZgCe rhOY6mmK0RSwcS7e3qlOxVYEQrraiIUjP3bQv/qOmwzfynOpk1AHSEaE9GYnGj8Mt3M4 OsGQ== X-Gm-Message-State: AOAM530Pc0THkCOoy7dQvpNoijQii/ifjFfC5/XlEGnXoLjcSjr1yUJu KDBUNooXQOYm5Enw3bnU/07J2sTKsqg= X-Google-Smtp-Source: ABdhPJwQq6F8WqPgssDkK316xH+EOL9K5I7Zk+JRICWMfnAuzhQ1SBCt+TZ0QVinRCUbkoAPUNMZBg== X-Received: by 2002:a1c:2b41:0:b0:392:9543:9782 with SMTP id r62-20020a1c2b41000000b0039295439782mr27173517wmr.124.1651086294025; Wed, 27 Apr 2022 12:04:54 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id o9-20020adf8b89000000b0020adeb916d8sm7155281wra.30.2022.04.27.12.04.52 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 27 Apr 2022 12:04:53 -0700 (PDT) Message-Id: In-Reply-To: References: Date: Wed, 27 Apr 2022 19:04:47 +0000 Subject: [PATCH 2/3] MyFirstContribution: also explain cover letter in GitGitGadget section Fcc: Sent MIME-Version: 1.0 To: git@vger.kernel.org Cc: Emily Shaffer , Johannes Schindelin , 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. Mention the purpose of the cover letter in that section, and give examples for the title and description, leveraging the excerpt extracted from the "Sending Patches with git send-email" section in the previous commit. Signed-off-by: Philippe Blain --- Documentation/MyFirstContribution.txt | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt index 681bbefe9cd..96da32f7cef 100644 --- a/Documentation/MyFirstContribution.txt +++ b/Documentation/MyFirstContribution.txt @@ -808,8 +808,20 @@ 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 as the +cover letter for your change. The cover letter describes your proposed +contribution as a whole and is ideal to mention any context that might be +useful for reviewers. The title of your PR should be something which +succinctly covers the purpose of your entire topic branch, for example: + +---- +Adding the 'psuh' command +---- + +Your PR's description will used as the body of the cover letter. +include::MyFirstContribution-coverletter.txt[] + +When you're happy, submit your pull request. [[run-ci-ggg]] === Running CI and Getting Ready to Send From patchwork Wed Apr 27 19:04:48 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Philippe Blain X-Patchwork-Id: 12829376 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 4253DC433EF for ; Wed, 27 Apr 2022 19:12:45 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232918AbiD0TPy (ORCPT ); Wed, 27 Apr 2022 15:15:54 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:35172 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S234198AbiD0TOM (ORCPT ); Wed, 27 Apr 2022 15:14:12 -0400 Received: from mail-wr1-x42d.google.com (mail-wr1-x42d.google.com [IPv6:2a00:1450:4864:20::42d]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id CE10C90CE8 for ; Wed, 27 Apr 2022 12:04:56 -0700 (PDT) Received: by mail-wr1-x42d.google.com with SMTP id q23so3810243wra.1 for ; Wed, 27 Apr 2022 12:04:56 -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=Z4W7EAoVPs/ZMACArphfVx1fvyrbGn1Y9FuVBcQgB6M=; b=K163+bZtq15VXeGlSbkYfd8QWRrKaWmeQFjgEZvibwig83RT+Q0nVWWmGwUCzWxqe+ bi6bTaCQFFQjV9swhEyMT95wjurjjZfnEsl7mEi+IsE24sPkujxV0CUf+O01Xdv71B8x /tZONIYFaGTJsbvUAxSIOwh/aleDQGd1LzRiGNrlK4HSKQYFHwziQkoLZUn8RBeGuYCH MjHU6Zya5NXUYH8mwhY/PkC17exZq9C2lgiAVIgYOxPUPIgLgA7Q5zpzOKp5kX2et8mP 2ngSHF+CyAZnKlTDEojAOa7bZbdXkI1VVM/mJFtuBP6RY89B7hjeapItl9+0jbzJ9BkU aPGQ== 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=Z4W7EAoVPs/ZMACArphfVx1fvyrbGn1Y9FuVBcQgB6M=; b=PZBIHfUtoUFTpSPBk2o8+j9lDySKswS2kcXnHZWauiVtl2ngrlFBgOiPItBydLlt3T uRXu4N7LIT/1hgaOdtsbhmSxwuAXe6Qiv6vl9lwB3tsWh/Pi6wKntYfQ+0Ka6Csb+kSM MA5vMjIXktM49rCGrqJd3NhxmvRck+hPfkqwdkeU49t9lb6KhKfGLlKF5ufimJN1woiH N7ocGbF+7rz5FO7q7j2tc4xVkgRASbI0jh34oeo0IjUG3qsnc0t1PfvBnOr0RiDBvBkJ IQzUkctwgN/YxFM7QvEsYRJ86aTXH+bfZt9cvHYWCfsnlNQ4C3ihRexL+oaahxMYM808 RYxA== X-Gm-Message-State: AOAM533dTvO0fIVgRQlb9BOHtbvalbWfK4KFU1WqLRsQepmWd/zbE54Q +6RTLO3E3mHUTHinIbJ3OdU9KgUHDi0= X-Google-Smtp-Source: ABdhPJz2jOt/tCWeoWyl4mknkDBMGOUA3bGWXOCNMTMYO5np9VNKxxuHbwu7THvZNU8LFQHmFGToNg== X-Received: by 2002:adf:ded0:0:b0:20a:f070:6bb0 with SMTP id i16-20020adfded0000000b0020af0706bb0mr3549150wrn.208.1651086295144; Wed, 27 Apr 2022 12:04:55 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id m1-20020a1ca301000000b003929c4bf250sm2216041wme.13.2022.04.27.12.04.54 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 27 Apr 2022 12:04:54 -0700 (PDT) Message-Id: <2f6ecbf260135efc2a7ad09564cf6c64ed6d6f0d.1651086288.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Wed, 27 Apr 2022 19:04:48 +0000 Subject: [PATCH 3/3] 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 , 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 | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt index 96da32f7cef..2ce51d8c82e 100644 --- a/Documentation/MyFirstContribution.txt +++ b/Documentation/MyFirstContribution.txt @@ -821,6 +821,14 @@ Adding the 'psuh' command Your PR's description will used as the body of the cover letter. include::MyFirstContribution-coverletter.txt[] +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, separately from your commit message. + When you're happy, submit your pull request. [[run-ci-ggg]]