Re: [PATCH 0/6] Create Git/Packet.pm

On Mon, Oct 23, 2017 at 01:26:41PM +0100, Philip Oakley wrote:

quoted

Totally offtopic, but is it only me who finds these "section
headers" in cover letters from some people irritating and/or
jarring?

Personally I find that, for significant patch series, that clearly breaking
out these distinct sections is of advantage. At this stage (the very first
patch 0/n) there is no specific conversation, so the subject line is a short
'hello' to the topic, and then the contributor is (it is to be hoped)
setting out their proposal in a clear manner.

So I do like these headings for larger series, though there is some
judgement to be made as to when the subject line alone is sufficient.

I can live with fancily-formatted cover letters. BUT. I would say if
your cover letter is getting quite long, you might consider whether some
of its content ought to be going elsewhere (either into commit messages
themselves, or into a design document or other place inside the repo).

As a separate follow on, one thing that does annoy me is that in subsequent
versions of the various patch series, folk tend to drop all explanation of
why the series is of any relevance, leaving just the 'changed since last
time' part. This means that new readers who try and pick up / review /
contribute to a series later on in its development are not told the purpose.
When the list is active it can, accidentally, do a disservice to the
potential contributors who may feel that only core contributors are able to
contribute.

I actually have the opposite opinion. I find it annoying to have to wade
through the same unchanged content for each round just to find the
little snippet of "here's what's changed".

I don't mind following a link to the previous iteration to read the
back-story if I wasn't involved (it's a good idea to do that anyway to
see what previous reviews have already discussed).

I do often just post my "v2" as a follow-up and assume people can find
the original by following the thread backwards. But I imagine that not
everybody can do so. It's probably a good practice to at least put a
link to the prior version (and also to v1 for the original motivation)
if you're not going to repeat the cover letter in full.

-Peff