On Mon, Oct 23, 2017 at 01:26:41PM +0100, Philip Oakley wrote: > > 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
