Re: [PATCH 2/3] MyFirstContribution: also explain cover letter in GitGitGadget section

From: Victoria Dye <vdye@github.com>
Date: Apr 29, 2022, 16:27 UTC
Message-ID: <f7f64135-7d57-5926-501b-13e83411b4fd@github.com>
In-Reply-To: <c7030c98-bd65-7d0e-89ac-ae291e22b10d@gmail.com>

Philippe Blain wrote:

Show 35 quoted lines

> Hi Victoria,
> 
> Le 2022-04-27 à 16:43, Victoria Dye a écrit :
>> Philippe Blain via GitGitGadget wrote:
> 
>>> +----
>>> +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"
>>
> 
> I fully agree. I just copied the existing patch series title from 
> the git-send-email section further down. I think it would make sense
> to change this to also using the imperative mood just like commit messages
> in a preparatory commit. I'll do that.
> 
>>> +----
>>> +
>>> +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.
> 
> I'm not exactly sure what you mean. I meant that the description of the PR
> will be used as the body of the cover letter...
>

Sorry for being unclear. What I meant was that, the way this part of the document reads (to me) right now, it looks like the recommendation is to create a pull request with the title & description:

Title: 
	Adding the 'psuh' command
Description:
	Your PR's description will [be] used as the body of the cover
	letter. <insert content from MyFirstContribution-coverletter.txt>

That is, the line "Your PR description will..." is the first line of the description (which I don't think was your intention).

That said, upon a more holistic re-read, I've found a few more things that are confusing/oddly phrased. I'll try re-reviewing (part of) the patch below, with (hopefully) more direct/concrete feedback this time:

Show 5 quoted lines

> -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

s/is ideal to/should(?)

Show 6 quoted lines

> +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
> +----

Other than the "Adding" -> "Add" change, this is good - the example title will be formatted as a monospaced block, clearly separating it from the advice/context preceding it.

> +
> +Your PR's description will used as the body of the cover letter.
> +include::MyFirstContribution-coverletter.txt[]
> +

Conversely, this section has no visible separation between the context ("Your PR's description...") and the example ("include::MyFirstContribution-coverletter.txt[]"), hence my confusion earlier.

To parallel the title example, maybe you could use similar monospace formatting for the example? E.g.:

+
+Your PR's description will used as the body of the cover letter.
+ 
+----
+include::MyFirstContribution-coverletter.txt[]
+----
+

One thing I noticed on my re-read is that the context you provide for the title ("The title of your PR should be something...") isn't quite paralleled in the context for the description ("Your PR's description..."). The former talks about *how* you should write your cover letter title, whereas the latter simply states that the PR description will become the cover letter's content. For added context, then, you might want to describe how the cover letter content should be written, e.g.:

+
+Your PR's description will be used as the body of the cover letter and
+should explain the purpose of the series, for example:
+ 
+----
+include::MyFirstContribution-coverletter.txt[]
+----
+

(note the s/will used/will be used)

Apologies for all the picky grammar comments - this series includes a lot of really helpful information for new contributors, and I really appreciate your work here! Hopefully my feedback is a bit more clear this time (and is relatively straightforward to implement).

Thanks!

> Thanks for having a look!
> 
> Philippe.