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

From: Jeff King <peff@peff.net>
Date: Oct 30, 2017, 18:08 UTC
Message-ID: <20171030180858.e6kp5uwac3kkoaae@sigill.intra.peff.net>
In-Reply-To: <8F505EA8D16F4A0F890AE9DEEB91434B@PhilipOakley>

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

Show 12 quoted lines

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

Show 8 quoted lines

> 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