This is the mail archive of the
gcc-patches@gcc.gnu.org
mailing list for the GCC project.
Re: [PATCH, v2] wwwdocs: e-mail subject lines for contributions
On Wed, Jan 22, 2020 at 10:00:00AM +0000, Richard Earnshaw (lists) wrote:
> On 21/01/2020 19:26, Segher Boessenkool wrote:
> >On Tue, Jan 21, 2020 at 02:52:00PM +0000, Richard Earnshaw (lists) wrote:
> >>+ <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?
Yes.
> 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.
The usual recommendation is 50 chars. Which is just about right with
most MUAs.
> >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.
Excellent.
> >>+<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.
This is just basic email etiquette :-)
But, it's very annoying when you look at badly formatted subjects, in
"git log --oneline" for example, it is very obvious there (and long
subjects are problematic there as well btw).
Wrt balance: yes, that is one reason why I do not think we should
require all the markup stuff.
> >>+<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.
Sure. Ah, we could recommend that then, to make it clear in the vM 0/N
of some series which patches changed how. My point is that it is a
waste of time to everyone if a reviewer has to drag through everything
every time; this is double true with git, it is easy to send updated
versions of patch sets often.
Segher