| Message ID | 2f6ecbf260135efc2a7ad09564cf6c64ed6d6f0d.1651086288.git.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | Improve MyFirstContribution's GitGitGadget section | expand |
"Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> writes: > +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. "separately from your commit message" wants to be clarified. It sounds as if GGG will send a separate message. I am _guessing_ that you meant something like "the body of your proposed log message ends with your sign-off and followed by a line with three-dashes on it. After that three-dash line, and before the diffstat and the patch, is an appropriate place to write additional information that are meant to help reviewers during review but will become irrelevant after the review is done. Your PR description will appear there for a single patch contribution". If we do not explain the space after the three-dash line elsewhere, perhaps we should do so separately, like we talk about cover letters. Thanks.
Le 2022-04-27 à 17:56, Junio C Hamano a écrit : > "Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> writes: > >> +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. > > "separately from your commit message" wants to be clarified. It > sounds as if GGG will send a separate message. > > I am _guessing_ that you meant something like "the body of your > proposed log message ends with your sign-off and followed by a line > with three-dashes on it. After that three-dash line, and before the > diffstat and the patch, is an appropriate place to write additional > information that are meant to help reviewers during review but will > become irrelevant after the review is done. Your PR description > will appear there for a single patch contribution". Yes, this is what I meant. I'll try to phrase it differently. > > If we do not explain the space after the three-dash line elsewhere, > perhaps we should do so separately, like we talk about cover > letters. Yeah, it is explained in the "Bonus Chapter: One-Patch Changes" subsection [1] at the end of the "Sending Patches with git send-email" section, so I guess people only reading the GitGitGadget instructions will not read that far... Considering your other comment, I think that a little section titled something like "Anatomy of a patch series" would make sense to introduce how then end product looks like and then the sections on GGG or git-send-email can reference this earlier section. Good idea. Thanks! Philippe. [1] https://git-scm.com/docs/MyFirstContribution#single-patch
Philippe Blain <levraiphilippeblain@gmail.com> writes: > Considering your other comment, I think that a little section > titled something like "Anatomy of a patch series" would make sense > to introduce how then end product looks like and then the sections > on GGG or git-send-email can reference this earlier section. "Anatomy" does sound like a good idea.
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]]