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

[Segher Boessenkool]

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.

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).

> +<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.

> +<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 :-)


Segher