| Message ID | 7e84d5b286de9dddf28ef1c8f38c7d7c28e266f0.1651086288.git.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | Improve MyFirstContribution's GitGitGadget section | expand |
On Wed, Apr 27, 2022 at 3:18 PM Philippe Blain via GitGitGadget <gitgitgadget@gmail.com> wrote: > 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 s/The/the s/form/from/ > 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 <levraiphilippeblain@gmail.com>
"Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> writes: > From: Philippe Blain <levraiphilippeblain@gmail.com> > > 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 <levraiphilippeblain@gmail.com> > --- > .../MyFirstContribution-coverletter.txt | 18 ++++++++++++++++ > Documentation/MyFirstContribution.txt | 21 ++----------------- > 2 files changed, 20 insertions(+), 19 deletions(-) > create mode 100644 Documentation/MyFirstContribution-coverletter.txt If the end-product is a single document, "MyFirstContribution", I am skeptical if it is a good change to duplicate the same text in two sections. Should we instead reorganize the document so these concepts like cover letters, log message for each commit, etc., which are applicable regardless of how you send them out, are explained, before we start talking about "now, we understand the components out of which a patch series is made of, here is how you give it a final polish and send it out, with send-email and/or with GGG"? Short of that, perhaps whichever appears later in the document that uses "cover letter" can just say "see above"?
Hi Eric, Le 2022-04-27 à 17:15, Eric Sunshine a écrit : > On Wed, Apr 27, 2022 at 3:18 PM Philippe Blain via GitGitGadget > <gitgitgadget@gmail.com> wrote: >> 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 > > s/The/the > s/form/from/ > Indeed, will fix. Thanks, Philippe.
Hi Junio, Le 2022-04-27 à 17:48, Junio C Hamano a écrit : > "Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> writes: > >> From: Philippe Blain <levraiphilippeblain@gmail.com> >> >> 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 <levraiphilippeblain@gmail.com> >> --- >> .../MyFirstContribution-coverletter.txt | 18 ++++++++++++++++ >> Documentation/MyFirstContribution.txt | 21 ++----------------- >> 2 files changed, 20 insertions(+), 19 deletions(-) >> create mode 100644 Documentation/MyFirstContribution-coverletter.txt > > If the end-product is a single document, "MyFirstContribution", I am > skeptical if it is a good change to duplicate the same text in two > sections. > > Should we instead reorganize the document so these concepts like > cover letters, log message for each commit, etc., which are > applicable regardless of how you send them out, are explained, > before we start talking about "now, we understand the components out > of which a patch series is made of, here is how you give it a final > polish and send it out, with send-email and/or with GGG"? > > Short of that, perhaps whichever appears later in the document that > uses "cover letter" can just say "see above"? > Yeah, I guess you are right. I choosed to factor out the cover letter part like this mostly because it was a smaller change. I'll think of doing it like you suggest. Thanks, Philippe.
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.