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

From: Philip Oakley <philipoakley@iee.org>
Date: Oct 23, 2017, 12:26 UTC
Message-ID: <8F505EA8D16F4A0F890AE9DEEB91434B@PhilipOakley>
In-Reply-To: <xmqq8tg4djkm.fsf@gitster.mtv.corp.google.com>

Hi Junio,

From: "Junio C Hamano" <gitster@pobox.com>

Show 8 quoted lines

> Christian Couder <christian.couder@gmail.com> writes:
>
>> Goal
>> ~~~~
>
> 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.

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.

Whether this series needed a Goal heading is separate discussion ;-)

Show 21 quoted lines

> ..          It perhaps is because I view the cover letter more as a
> part of conversation, not a presentation.  And when you walk up to
> somebody and start a conversation, you do not declare section
> headers ;-)
>
> Saying "I want to be able to do these things in the future, and here
> is to prepare for that future" at the beginning nevertheless is a
> good thing.  It gives us readers an overall vision we can agree to
> (or be against, or offer alternatives) and sets expectations on what
> the series would do and where it stops and leaves the remainder to
> follow-up work.
>
>> Packet related functions in Perl can be useful to write new filters or
>> to debug or test existing filters. So instead of having them in
>> t0021/rot13-filter.pl, let's extract them into a new Git/Packet.pm
>> module.
>
> I left some comments on individual patches to point out places that
> may need improvements.  I agree with the overall direction.
>
> Thanks for starting this topic.

-- Philip