[PATCH, v2] wwwdocs: e-mail subject lines for contributions

Richard Earnshaw (lists) Richard.Earnshaw@arm.com
Wed Jan 22 16:05:00 GMT 2020


On 21/01/2020 19:26, Segher Boessenkool wrote:
> Hi!
> 
> Thanks for doing this.
> 
> On Tue, Jan 21, 2020 at 02:52:00PM +0000, Richard Earnshaw (lists) wrote:
>> This patch proposes some new (additional) rules for email subject lines
>> when contributing to GCC.  The goal is to make sure that, as far as
>> possible, the subject for a patch will form a good summary when the
>> message is committed to the repository if applied with 'git am'.
> 
>> +<p>A high-quality e-mail subject line for a contribution contains the
>> +following elements:</p>
> 
>> +  <li>A brief summary</li>
> 
> You could stress that this is the one thing that really matters.  And
> it's not a summary, it's much too brief for that (at most ~50 chars),
> but yup it should be something that allows *a human* to identify what
> this is.
> 

Well, it should all matter, or why are we requiring it?

I'm happy to insert 'very' in front of 'brief' and to say elsewhere that 
the entire subject (less the leading [...] part, should rarely, if ever, 
go beyond 80 characters.

> Everything else is just convention.
> 
>> +<p>A component tag is a short identifier that identifies the part of
>> +the compiler being modified.  This highlights to the relevant
>> +maintainers that the patch may need their attention.  Multiple
>> +components may be listed if necessary.  Each component tag should be
>> +followed by a colon.
> 
> Often people use aaa/bbb: if drilling down a bit that way helps keep the
> subject short (which is the *point* of all this: keep things better
> consumable for humans).

The aaa: bbb: is really for when aaa and bbb are independent parts of 
the compiler and potentially needs multiple reviewers. aaa/bbb is when 
bbb is strictly a sub-component of aaa (for example, arm/SVE: would be 
an SVE related issue in the arm backend).  I'm certainly not against 
having that.

> 
>> +<p>The brief summary encapsulates in a few words the intent of the
>> +change.  For example: <code>cleanup check_field_decls</code>.</p>
> 
> It should start with a capital though.  "Clean up blablal".  (So no
> dot to end the sentence, this isn't a sentence).  A capital helps
> the reader to quickly identify what is what, separate fluff from the
> core parts.
> 

There is a balance here to be made.  I'm mindful of Gerald's concern 
that this is perhaps overly restrictive for new users already.  I 
certainly think we should have a good house style, but getting too 
prescriptive just gets in the way of attracting good contributions.

>> +<p>Some large patch sets benefit from an introductory e-mail that
>> +provides more context for the patch series and describes how the
>> +patches have been broken up to provide for review.
> 
> All non-trivial series, yeah.
> 
> Maybe we should mention how v2 etc. of patch series should show what is
> changed?  If there is a good standard practice for that at all :-)
> 

Dunno.  I think that belongs primarily in the v2 0/n mail.  It's not, 
after all, something that needs to be kept once the patches are applied.

R.
> 
> Segher
> 



More information about the Gcc mailing list