Philippe Blain via GitGitGadget wrote: > From: Philippe Blain <levraiphilippeblain@xxxxxxxxx> > > 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 <levraiphilippeblain@xxxxxxxxx> > --- > 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 Typically I see patch series titles follow the same "imperative mood" as commit titles/messages (see 'Documentation/SubmittingPatches.txt'). I'm not sure whether that's a rule written down somewhere or just convention, but for the sake of consistency you might want to do something like: "Add the 'psuh' command" > +---- > + > +Your PR's description will used as the body of the cover letter. Including the line "Your PR's description..." is somewhat confusing to me as a first-time reader, since I was interpreting this section to be the *verbatim* text of the pull request title & description. If this *is* meant to be that description, then the note about the PR description can be removed. That point is also mentioned above, so it's probably not needed here anyway. > +include::MyFirstContribution-coverletter.txt[] > + > +When you're happy, submit your pull request. > > [[run-ci-ggg]] > === Running CI and Getting Ready to Send
