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
