This is the mail archive of the
gcc@gcc.gnu.org
mailing list for the GCC project.
Re: [PATCH, v2] wwwdocs: e-mail subject lines for contributions
- From: Segher Boessenkool <segher at kernel dot crashing dot org>
- To: "Richard Earnshaw (lists)" <Richard dot Earnshaw at arm dot com>
- Cc: Gerald Pfeifer <gerald at pfeifer dot com>, gcc-patches at gcc dot gnu dot org, GCC Development <gcc at gcc dot gnu dot org>
- Date: Tue, 21 Jan 2020 13:26:50 -0600
- Subject: Re: [PATCH, v2] wwwdocs: e-mail subject lines for contributions
- References: <c3928f40-2d71-fb5b-f2e0-3878ac88a2b7@arm.com> <alpine.LSU.2.21.2001191425160.739@anthias.pfeifer.com> <353faf3e-bf43-eb4d-542d-45a53dce77b2@arm.com> <ff130918-cbbb-2afc-d752-1af2ca9df340@arm.com>
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