On Mon, Nov 20, 2017 at 09:48:58PM -1000, Linus Torvalds wrote:
> On Mon, Nov 20, 2017 at 9:06 AM, Darren Hart <dvh...@infradead.org> wrote:
> >
> > Back in the 4.2 timeframe, platform-drivers-x86-v4.2-2 specifically, I
> > started adding my pull request commentary to the tag directly and the
> > pull requests themselves tended to have little or no information beyond
> > that.
>
> Right - that's fine. I don't actually care whether the information is
> in the signed tag, or in the emailed pull request, or in both. I'll
> take it either way.
>
> There are valid reasons to put it in the signed tag - that way you
> write it as you do the tag, and then "git pull-request" is pretty much
> entirely just automation.
>
> But some people prefer to do the tag as just a marker (so the tag
> message may be basically worthless), and then write the explanation
> later in the email as they send it off. And that's fine too.
>
> And yet other people do both - write some summary in the tag, but hen
> write more about it in the emailed message. And I'll take that too, no
> problem.
>
> And in all three cases I'll edit things for grammar and whitespace
> (indentation) etc, and may remove commentary that may be interesting
> for me doing the merge, but isn't relevant in the history once the
> merge is done.
>
> > I didn't see a clear division between what should go in the pull
> > request email body and what should be in the tag, this kept all the
> > information about the pull request together in the tag.
>
> There really is no division at all. One common _pattern_ is to have
> the email message contain more of a freeform message, while the tag
> contains more of a "summary list", but that's just a pattern that some
> people tend to use, and it's not in any way universal or required.
>
> > Andy's pull request follows this pattern, with the text of the tag
> > opening with the summary and context relevant to the pull request before
> > the munged shortlog:
>
> Yes, and that separation is fine.
>
> But I do want both parts to make sense. If the munged shortlog is pure
> automation, why send it to me at all? Or if you do send it to me, say
> that it's just filler for _you_, not for me.
>
> But it looks like useful information, but without human editing, it's not.
>
> It's basically the difference between "data" and "information". I want
> information, and if it's pure data that I could get from "git
> shortlog" that I should just ignore, then tell me to ignore it.
Thanks Linus, this is helpful. Andy and I have updated our tooling to
reflect the above, and we will modify our human-information-add as
follows:
The pull-request body will include merge-specific information and
instructions which are unrelated to the content. e.g. previously merged
fixes, pre-merged immutable branches, recommended merge conflict
resolution.
The tag message will include a human written highlights and summary,
followed by a git shortlog grouped by driver with a prefix indicating it
is automatically generated (although we will still verify the script
grouped things properly). This just offers a quick glance at what
changed by driver. I will also sometimes group fixes from static
analysis that would otherwise be rather noisy under a common group, e.g.
sparse fixes:
- Updated several drivers to use const strings
--
Darren Hart
VMware Open Source Technology Center
