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

["Richard Earnshaw (lists)" <Richard dot Earnshaw at arm dot com>]

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