[v3] wwwdocs: e-mail subject lines for contributions

Message ID 91e48c52-4548-089b-707a-afd400001dac@arm.com
State New
Headers show
Series
  • [v3] wwwdocs: e-mail subject lines for contributions
Related show

Commit Message

Richard Earnshaw (lists) Jan. 22, 2020, 5:45 p.m.
[updated based on v2 discussions]

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'.  Where
possible, I've tried to align these rules with those already in
use for glibc, so that the differences are minimal and only where
necessary.

Some things that differ from existing practice (at least by some people)
are:

- Use '<topic>:' rather than '[<topic>]'
   - This is more git friendly and works with 'git am'.
- Put bug numbers at the end of the line rather than the beginning.
   - The bug number is useful, but not as useful as the brief summary.
     Also, use the shortened form, as the topic part is more usefully
     conveyed in the proper topic field (see above).

Comments

Richard Earnshaw (lists) Feb. 3, 2020, 11:41 a.m. | #1
On 22/01/2020 17:45, Richard Earnshaw (lists) wrote:
> 

> [updated based on v2 discussions]

> 

> 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'.  Where

> possible, I've tried to align these rules with those already in

> use for glibc, so that the differences are minimal and only where

> necessary.

> 

> Some things that differ from existing practice (at least by some people)

> are:

> 

> - Use '<topic>:' rather than '[<topic>]'

>    - This is more git friendly and works with 'git am'.

> - Put bug numbers at the end of the line rather than the beginning.

>    - The bug number is useful, but not as useful as the brief summary.

>      Also, use the shortened form, as the topic part is more usefully

>      conveyed in the proper topic field (see above).


I've not seen any follow-up to this version.  Should we go ahead and 
adopt this?

R.
Alexander Monakov Feb. 3, 2020, 11:54 a.m. | #2
On Mon, 3 Feb 2020, Richard Earnshaw (lists) wrote:

> I've not seen any follow-up to this version.  Should we go ahead and adopt

> this?


Can we please go with 'committed' (lowercase) rather than all-caps COMMITTED?
Spelling this with all-caps seems like a recent thing on gcc-patches, before
everyone used the lowercase version, which makes more sense (no need to shout
about the thing that didn't need any discussion before applying the patch).

Also, while tools like 'git format-patch' will automatically put [PATCH] in
the subject, for '[COMMITTED]' it will be the human typing that out, and
it makes little sense to require people to meticulously type that out in caps.
Especially when the previous practice was opposite.

Thanks.
Alexander
Richard Earnshaw (lists) Feb. 3, 2020, 11:59 a.m. | #3
On 03/02/2020 11:54, Alexander Monakov wrote:
> On Mon, 3 Feb 2020, Richard Earnshaw (lists) wrote:

> 

>> I've not seen any follow-up to this version.  Should we go ahead and adopt

>> this?

> 

> Can we please go with 'committed' (lowercase) rather than all-caps COMMITTED?

> Spelling this with all-caps seems like a recent thing on gcc-patches, before

> everyone used the lowercase version, which makes more sense (no need to shout

> about the thing that didn't need any discussion before applying the patch).

> 

> Also, while tools like 'git format-patch' will automatically put [PATCH] in

> the subject, for '[COMMITTED]' it will be the human typing that out, and

> it makes little sense to require people to meticulously type that out in caps.

> Especially when the previous practice was opposite.

> 

> Thanks.

> Alexander

> 


Upper case is what glibc has, though it appears that it's a rule that is 
not strictly followed.  If we change it, then it becomes another 
friction point between developer groups.  Personally, I'd leave it as 
is, then turn a blind eye to such minor non-conformance.

Quite frankly, then bit that matters most is what follows that, since 
that is what gets written into the git commit message.

R.
Alexander Monakov Feb. 3, 2020, 12:50 p.m. | #4
On Mon, 3 Feb 2020, Richard Earnshaw (lists) wrote:

> Upper case is what glibc has, though it appears that it's a rule that is not

> strictly followed.  If we change it, then it becomes another friction point

> between developer groups.  Personally, I'd leave it as is, then turn a blind

> eye to such minor non-conformance.


In that case can we simply say that both 'committed' and 'COMMITTED' are okay,
if we know glibc doesn't follow that rule and anticipate we will not follow
it either?

Thanks.
Alexander
Segher Boessenkool Feb. 3, 2020, 1:54 p.m. | #5
On Mon, Feb 03, 2020 at 02:54:05PM +0300, Alexander Monakov wrote:
> On Mon, 3 Feb 2020, Richard Earnshaw (lists) wrote:

> 

> > I've not seen any follow-up to this version.  Should we go ahead and adopt

> > this?

> 

> Can we please go with 'committed' (lowercase) rather than all-caps COMMITTED?

> Spelling this with all-caps seems like a recent thing on gcc-patches, before

> everyone used the lowercase version, which makes more sense (no need to shout

> about the thing that didn't need any discussion before applying the patch).


Lower case certainly makes more sense.

None of this are *rules*.  We should not pretend they are.  An email
subject should be useful to what the receivers of that email use it for:
see if it very interesting to them, see if it probably not interesting
to them: that's the "smth: " at the start, and the PR number at the end,
and of course the actual subject itself, so we should not put in too
much fluff in the subject, there needs to be room left (in the less than
fifty chars total) for an actual subject :-)

(The example in the patch does not capitalise the subject line, btw.
It should.)


Segher
Richard Earnshaw (lists) Feb. 3, 2020, 1:59 p.m. | #6
On 03/02/2020 13:54, Segher Boessenkool wrote:
> On Mon, Feb 03, 2020 at 02:54:05PM +0300, Alexander Monakov wrote:

>> On Mon, 3 Feb 2020, Richard Earnshaw (lists) wrote:

>>

>>> I've not seen any follow-up to this version.  Should we go ahead and adopt

>>> this?

>>

>> Can we please go with 'committed' (lowercase) rather than all-caps COMMITTED?

>> Spelling this with all-caps seems like a recent thing on gcc-patches, before

>> everyone used the lowercase version, which makes more sense (no need to shout

>> about the thing that didn't need any discussion before applying the patch).

> 

> Lower case certainly makes more sense.

> 

> None of this are *rules*.  We should not pretend they are.  An email

> subject should be useful to what the receivers of that email use it for:

> see if it very interesting to them, see if it probably not interesting

> to them: that's the "smth: " at the start, and the PR number at the end,

> and of course the actual subject itself, so we should not put in too

> much fluff in the subject, there needs to be room left (in the less than

> fifty chars total) for an actual subject :-)

> 

> (The example in the patch does not capitalise the subject line, btw.

> It should.)

> 

> 

> Segher

> 



Where does your '50 chars' limit come from?  It's not in the glibc text, 
and it's not in the linux kernel text either.  AFAICT this is your 
invention and you seem to be the only person proposing it.

I think the linux rule (the whole line, not including the parts that are 
removed on commit, should not exceed 75 characters) is far more sensible 
- which is why this draft states this.

R.
Jason Merrill Feb. 3, 2020, 2:10 p.m. | #7
On Mon, Feb 3, 2020 at 7:57 AM Alexander Monakov <amonakov@ispras.ru> wrote:

> On Mon, 3 Feb 2020, Richard Earnshaw (lists) wrote:

>

> > Upper case is what glibc has, though it appears that it's a rule that is

> not

> > strictly followed.  If we change it, then it becomes another friction

> point

> > between developer groups.  Personally, I'd leave it as is, then turn a

> blind

> > eye to such minor non-conformance.

>

> In that case can we simply say that both 'committed' and 'COMMITTED' are

> okay,

> if we know glibc doesn't follow that rule and anticipate we will not follow

> it either?

>


And perhaps something shorter?  "committed" is a long word.  [PUSHED]?

Jason
Jonathan Wakely Feb. 3, 2020, 2:13 p.m. | #8
On Mon, 3 Feb 2020 at 14:00, Richard Earnshaw (lists) wrote:
> Where does your '50 chars' limit come from?  It's not in the glibc text,

> and it's not in the linux kernel text either.  AFAICT this is your

> invention and you seem to be the only person proposing it.


It's a fairly well established convention, e.g.
https://chris.beams.io/posts/git-commit/ and it's what Github suggests
(and whines if you go past it).

> I think the linux rule (the whole line, not including the parts that are

> removed on commit, should not exceed 75 characters) is far more sensible

> - which is why this draft states this.


I'm OK with that.
Richard Earnshaw (lists) Feb. 3, 2020, 3:04 p.m. | #9
On 03/02/2020 14:13, Jonathan Wakely wrote:
> On Mon, 3 Feb 2020 at 14:00, Richard Earnshaw (lists) wrote:

>> Where does your '50 chars' limit come from?  It's not in the glibc text,

>> and it's not in the linux kernel text either.  AFAICT this is your

>> invention and you seem to be the only person proposing it.

> 

> It's a fairly well established convention, e.g.

> https://chris.beams.io/posts/git-commit/ and it's what Github suggests

> (and whines if you go past it).

> 


That suggest it as a limit for everything.  If you have a tag and a bug 
number then then that would leave very little for the real part of the 
summary and would likely lead to something meaningless or 
incomprehensible in the remaining characters.  That might be OK for 
small projects, but for something the size of gcc, I think keeping the 
extra flexibility is useful.

>> I think the linux rule (the whole line, not including the parts that are

>> removed on commit, should not exceed 75 characters) is far more sensible

>> - which is why this draft states this.

> 

> I'm OK with that.

> 


OK, thanks.

R.
Richard Earnshaw (lists) Feb. 3, 2020, 3:13 p.m. | #10
On 03/02/2020 14:10, Jason Merrill wrote:
> On Mon, Feb 3, 2020 at 7:57 AM Alexander Monakov <amonakov@ispras.ru> wrote:

> 

>> On Mon, 3 Feb 2020, Richard Earnshaw (lists) wrote:

>>

>>> Upper case is what glibc has, though it appears that it's a rule that is

>> not

>>> strictly followed.  If we change it, then it becomes another friction

>> point

>>> between developer groups.  Personally, I'd leave it as is, then turn a

>> blind

>>> eye to such minor non-conformance.

>>

>> In that case can we simply say that both 'committed' and 'COMMITTED' are

>> okay,

>> if we know glibc doesn't follow that rule and anticipate we will not follow

>> it either?

>>

> 

> And perhaps something shorter?  "committed" is a long word.  [PUSHED]?

> 

> Jason

> 


"Committed" is the accepted term in glibc.  If we insist on something 
different, then that becomes a friction point.

On the other hand, I really don't care personally as long as the meaning 
is clear.  I'd be happy with the super-set of all of these, since it 
only appears in email messages, not the final commit.

R.
Richard Earnshaw (lists) Feb. 3, 2020, 3:15 p.m. | #11
On 03/02/2020 15:13, Richard Earnshaw (lists) wrote:
> On 03/02/2020 14:10, Jason Merrill wrote:

>> On Mon, Feb 3, 2020 at 7:57 AM Alexander Monakov <amonakov@ispras.ru> 

>> wrote:

>>

>>> On Mon, 3 Feb 2020, Richard Earnshaw (lists) wrote:

>>>

>>>> Upper case is what glibc has, though it appears that it's a rule 

>>>> that is

>>> not

>>>> strictly followed.  If we change it, then it becomes another friction

>>> point

>>>> between developer groups.  Personally, I'd leave it as is, then turn a

>>> blind

>>>> eye to such minor non-conformance.

>>>

>>> In that case can we simply say that both 'committed' and 'COMMITTED' are

>>> okay,

>>> if we know glibc doesn't follow that rule and anticipate we will not 

>>> follow

>>> it either?

>>>

>>

>> And perhaps something shorter?  "committed" is a long word.  [PUSHED]?

>>

>> Jason

>>

> 

> "Committed" is the accepted term in glibc.  If we insist on something 

> different, then that becomes a friction point.

> 


"COMMITTED", not "Committed".

> On the other hand, I really don't care personally as long as the meaning 

> is clear.  I'd be happy with the super-set of all of these, since it 

> only appears in email messages, not the final commit.

> 

> R.
Andrew Clayton Feb. 3, 2020, 4:12 p.m. | #12
On Mon, 3 Feb 2020 15:04:57 +0000
"Richard Earnshaw (lists)" <Richard.Earnshaw@arm.com> wrote:

> On 03/02/2020 14:13, Jonathan Wakely wrote:

> > On Mon, 3 Feb 2020 at 14:00, Richard Earnshaw (lists) wrote:  

> >> Where does your '50 chars' limit come from?  It's not in the glibc text,

> >> and it's not in the linux kernel text either.  AFAICT this is your

> >> invention and you seem to be the only person proposing it.  

> > 

> > It's a fairly well established convention, e.g.

> > https://chris.beams.io/posts/git-commit/ and it's what Github suggests

> > (and whines if you go past it).

> >   

> 

> That suggest it as a limit for everything.  If you have a tag and a bug 

> number then then that would leave very little for the real part of the 

> summary and would likely lead to something meaningless or 

> incomprehensible in the remaining characters.  That might be OK for 

> small projects, but for something the size of gcc, I think keeping the 

> extra flexibility is useful.


Hopefully I've been following this discussion properly.

It's important to clarify that there are two *limits* in play here.

The subject should generally be kept to 50 chars or less, This is
because the subject is displayed in the output of commands like
'git log --oneline' and 'git shortlog' which indents more than git log.

Then the message body should wrap after 72-75 chars, again as the
output of the likes of 'git log' indent the message by 4 chars.

Using vim as the git commit message editor, vim will show you when your
subject line is over 50 chars and it wraps the message body after 72
chars.

Cheers,
Andrew
Segher Boessenkool Feb. 3, 2020, 5:17 p.m. | #13
On Mon, Feb 03, 2020 at 01:59:58PM +0000, Richard Earnshaw (lists) wrote:
> On 03/02/2020 13:54, Segher Boessenkool wrote:

> >None of this are *rules*.  We should not pretend they are.  An email

> >subject should be useful to what the receivers of that email use it for:

> >see if it very interesting to them, see if it probably not interesting

> >to them: that's the "smth: " at the start, and the PR number at the end,

> >and of course the actual subject itself, so we should not put in too

> >much fluff in the subject, there needs to be room left (in the less than

> >fifty chars total) for an actual subject :-)

> >

> >(The example in the patch does not capitalise the subject line, btw.

> >It should.)

> 

> Where does your '50 chars' limit come from?  It's not in the glibc text, 

> and it's not in the linux kernel text either.  AFAICT this is your 

> invention and you seem to be the only person proposing it.


Ha, no.

It seems it originally is from
https://github.com/git/git/commit/927a503cd07718ea0f700052043f383253904a56
and it has been part of "man git commit" since
https://github.com/git/git/commit/936f32d3de468db8daf853155ddd5c6b191af60c
(2006 and 2007, resp.)


Segher
Segher Boessenkool Feb. 3, 2020, 5:19 p.m. | #14
On Mon, Feb 03, 2020 at 01:59:58PM +0000, Richard Earnshaw (lists) wrote:
> On 03/02/2020 13:54, Segher Boessenkool wrote:

> >None of this are *rules*.  We should not pretend they are.  An email

> >subject should be useful to what the receivers of that email use it for:

> >see if it very interesting to them, see if it probably not interesting

> >to them: that's the "smth: " at the start, and the PR number at the end,

> >and of course the actual subject itself, so we should not put in too

> >much fluff in the subject, there needs to be room left (in the less than

> >fifty chars total) for an actual subject :-)

> >

> >(The example in the patch does not capitalise the subject line, btw.

> >It should.)

> 

> Where does your '50 chars' limit come from?  It's not in the glibc text, 

> and it's not in the linux kernel text either.  AFAICT this is your 

> invention and you seem to be the only person proposing it.

> 

> I think the linux rule (the whole line, not including the parts that are 

> removed on commit, should not exceed 75 characters) is far more sensible 

> - which is why this draft states this.


Oh, and it's not a limit, just a strong recommendation.


Segher
Michael Matz Feb. 3, 2020, 5:31 p.m. | #15
Hello,

On Mon, 3 Feb 2020, Richard Earnshaw (lists) wrote:

> Where does your '50 chars' limit come from?  It's not in the glibc text, 

> and it's not in the linux kernel text either.  AFAICT this is your 

> invention and you seem to be the only person proposing it.


Nope, it's fairly common, so much so that it's included in the "commonly 
accepted rules" that googling for "git subject lines" gives you (as a 
snippet glimpse from some website), and that vim changes color when 
spilling over 50 chars.  I actually thought it was universal and obvious 
until this thread (which is why I admittedly only did the above google 
right before writing this mail).  For the rationale: 'git log --oneline' 
with hash and author or date should fit the usual 72 char limit.  (An 
11-character hash plus space alone would come out as 60 chars for the 
subject)

That's also the reason why some people (certainly me) are nervous about or 
dislike all the "tags" in the subject line.  E.g. what essential 
information (and subjects are for essential info, right?) is "[committed]" 
(or, even worse "[patch]") supposed to transport?  If the rest of the 
subject doesn't interest me, I don't care if something was committed or 
not; if it _does_ interest me, then I'm going to look at the mail/patch 
either way, if committed or not; at which point the info if the author 
required review or has already committed it could be gives in the body as 
well.  Similar for some other metainfo tags.  (The "subsystem:" is good, 
though).

And if we must have these tags, then why not at least short ones?  Why 
isn't "[cmt]" or something enough?  There will be very few tags, so they 
become mnemonic pretty much immediately.  What becomes clearer when 
writing "[patch v2 1/13]" in comparison to "[v2 1/13]"?


Ciao,
Michael.
Segher Boessenkool Feb. 3, 2020, 5:34 p.m. | #16
On Mon, Feb 03, 2020 at 01:59:58PM +0000, Richard Earnshaw (lists) wrote:
> I think the linux rule (the whole line, not including the parts that are 

> removed on commit, should not exceed 75 characters) is far more sensible 

> - which is why this draft states this.


FWIW, on a slightly older kernel tree:

$ git log --oneline --format=%s|awk '{print length}'|sort -n|uniq -c|sort -r -n|head -10
  25059 50
  24872 49
  24563 47
  24547 48
  24261 51
  24050 52
  23773 53
  23527 46
  23231 54
  22907 45

On git.git:
$ git log --oneline --format=%s|awk '{print length}'|sort -n|uniq -c|sort -r -n|head -10
   1694 50
   1657 49
   1649 44
   1623 46
   1621 48
   1606 43
   1579 45
   1558 47
   1544 51
   1499 37


Sometimes longer subject lines are unavoidable.  Most of the time they
can be pretty easily avoided, and they hurt usability.  It is okay to
spend a few minutes on it, think of the thousands of people who will
later read it.


Segher
Richard Earnshaw (lists) Feb. 3, 2020, 5:36 p.m. | #17
On 03/02/2020 17:31, Michael Matz wrote:
> Hello,

> 

> On Mon, 3 Feb 2020, Richard Earnshaw (lists) wrote:

> 

>> Where does your '50 chars' limit come from?  It's not in the glibc text,

>> and it's not in the linux kernel text either.  AFAICT this is your

>> invention and you seem to be the only person proposing it.

> 

> Nope, it's fairly common, so much so that it's included in the "commonly

> accepted rules" that googling for "git subject lines" gives you (as a

> snippet glimpse from some website), and that vim changes color when

> spilling over 50 chars.  I actually thought it was universal and obvious

> until this thread (which is why I admittedly only did the above google

> right before writing this mail).  For the rationale: 'git log --oneline'

> with hash and author or date should fit the usual 72 char limit.  (An

> 11-character hash plus space alone would come out as 60 chars for the

> subject)

> 

> That's also the reason why some people (certainly me) are nervous about or

> dislike all the "tags" in the subject line.  E.g. what essential

> information (and subjects are for essential info, right?) is "[committed]"

> (or, even worse "[patch]") supposed to transport?  If the rest of the

> subject doesn't interest me, I don't care if something was committed or

> not; if it _does_ interest me, then I'm going to look at the mail/patch

> either way, if committed or not; at which point the info if the author

> required review or has already committed it could be gives in the body as

> well.  Similar for some other metainfo tags.  (The "subsystem:" is good,

> though).

> 

> And if we must have these tags, then why not at least short ones?  Why

> isn't "[cmt]" or something enough?  There will be very few tags, so they

> become mnemonic pretty much immediately.  What becomes clearer when

> writing "[patch v2 1/13]" in comparison to "[v2 1/13]"?

> 


The idea is that the [...] part is NOT part of the commit, only part of 
the email.  'git am' would strip leading [...] automatically unless 
you've configured, or asked git to do otherwise.  So that leading part 
is not counted for the length calculation.

R.

> 

> Ciao,

> Michael.

>
Michael Matz Feb. 3, 2020, 5:48 p.m. | #18
Hi,

On Mon, 3 Feb 2020, Richard Earnshaw (lists) wrote:

> The idea is that the [...] part is NOT part of the commit, only part of 

> the email.


I understand that, but the subject line of this thread says "e-mail 
subject lines", so I thought we were talking about, well, exactly that; 
and I see no value of these tags in e-mails either.

(They might have a low but non-zero value for projects that use 
a single mailing list for patches and generic discussion, but we are not 
such project)

Basically: if they are deemed to clutter the git log for whatever reason, 
then there must be a very good argument for why they not also clutter 
e-mail subject lines, but instead are essential to have there, 
but not in the log.

> 'git am' would strip leading [...] automatically unless 

> you've configured, or asked git to do otherwise.  So that leading part 

> is not counted for the length calculation.


There's still e-mail netiquette which also should be obeyed, or at least 
not contradicted by git netiquette.


Ciao,
Michael.
Jakub Jelinek Feb. 3, 2020, 5:54 p.m. | #19
On Mon, Feb 03, 2020 at 05:48:57PM +0000, Michael Matz wrote:
> On Mon, 3 Feb 2020, Richard Earnshaw (lists) wrote:

> 

> > The idea is that the [...] part is NOT part of the commit, only part of 

> > the email.

> 

> I understand that, but the subject line of this thread says "e-mail 

> subject lines", so I thought we were talking about, well, exactly that; 

> and I see no value of these tags in e-mails either.


In email, they do carry information that is useful there, the distinction
whether a patch has been committed already and doesn't need review from
others, or whether it is a patch intended for patch review, or just a RFC
patch that is not yet ready for review, but submitter is looking for some
feedback.

	Jakub
Richard Earnshaw (lists) Feb. 3, 2020, 5:54 p.m. | #20
On 03/02/2020 17:48, Michael Matz wrote:
> Hi,

> 

> On Mon, 3 Feb 2020, Richard Earnshaw (lists) wrote:

> 

>> The idea is that the [...] part is NOT part of the commit, only part of

>> the email.

> 

> I understand that, but the subject line of this thread says "e-mail

> subject lines", so I thought we were talking about, well, exactly that;

> and I see no value of these tags in e-mails either.

> 

> (They might have a low but non-zero value for projects that use

> a single mailing list for patches and generic discussion, but we are not

> such project)

> 

> Basically: if they are deemed to clutter the git log for whatever reason,

> then there must be a very good argument for why they not also clutter

> e-mail subject lines, but instead are essential to have there,

> but not in the log.

> 


Well, I'd review a patch differently depending on whether or not it was 
already committed, a patch requiring review or an RFC looking for more 
general comments, so I *do* think such an email prefix is useful.

>> 'git am' would strip leading [...] automatically unless

>> you've configured, or asked git to do otherwise.  So that leading part

>> is not counted for the length calculation.

> 

> There's still e-mail netiquette which also should be obeyed, or at least

> not contradicted by git netiquette.

> 


The 50 char limit seems to come from wanting git log --oneline to not 
wrap in an 80 column terminal.  Whilst laudable, I'm not sure that such 
a limit doesn't become too restrictive and then lead to 
hard-to-understand summaries.

R.
Joseph Myers Feb. 3, 2020, 6:03 p.m. | #21
On Mon, 3 Feb 2020, Michael Matz wrote:

> I understand that, but the subject line of this thread says "e-mail 

> subject lines", so I thought we were talking about, well, exactly that; 

> and I see no value of these tags in e-mails either.


I agree that [PATCH] is not useful (and in general, anything in the 
subject line before the actual meaningful commit summary should be as 
short as possible).  [RFC] might be useful, but not [PATCH].

-- 
Joseph S. Myers
joseph@codesourcery.com
Michael Matz Feb. 3, 2020, 6:09 p.m. | #22
Hello,

On Mon, 3 Feb 2020, Jakub Jelinek wrote:

> > > The idea is that the [...] part is NOT part of the commit, only part of 

> > > the email.

> > 

> > I understand that, but the subject line of this thread says "e-mail 

> > subject lines", so I thought we were talking about, well, exactly that; 

> > and I see no value of these tags in e-mails either.

> 

> In email, they do carry information that is useful there, the distinction

> whether a patch has been committed already and doesn't need review from

> others, or whether it is a patch intended for patch review, or just a RFC

> patch that is not yet ready for review, but submitter is looking for some

> feedback.


For tags like [cmt] or [rfc] I don't have much gripe, though I do think 
that info could be given in the body, and that e.g. in e-mail archives 
(where the tags are not removed automatically) they carry the same value 
as in git log, namely zero.

But suggesting that using the subject line for tagging is recommended can 
lead to subjects like

 [PATCH][GCC][Foo][component] Fix foo component bootstrap failure

in an e-mail directed to gcc-patches@gcc.gnu.org (from somewhen last year, 
where Foo/foo was an architecture; I'm really not trying to single out the 
author).  That is, _none_ of the four tags carried any informational 
content.


Ciao,
Michael.
Michael Matz Feb. 3, 2020, 6:20 p.m. | #23
Hello,

On Mon, 3 Feb 2020, Richard Earnshaw (lists) wrote:

> Well, I'd review a patch differently depending on whether or not it was 

> already committed, a patch requiring review or an RFC looking for more 

> general comments, so I *do* think such an email prefix is useful.


As I said: a very good argument must be made; it might be that rfc falls 
into the useful-tag category.

> >> 'git am' would strip leading [...] automatically unless

> >> you've configured, or asked git to do otherwise.  So that leading part

> >> is not counted for the length calculation.

> > 

> > There's still e-mail netiquette which also should be obeyed, or at least

> > not contradicted by git netiquette.

> 

> The 50 char limit seems to come from wanting git log --oneline to not wrap in

> an 80 column terminal.  Whilst laudable, I'm not sure that such a limit

> doesn't become too restrictive and then lead to hard-to-understand summaries.


In my experience hard-to-understand summaries are more related to people 
writing them than to length, IOW, I fear a larger limit like 72 characters 
won't help that.  And, as Segher put it, we aren't really talking about 
limits, only about suggestions, if you _really_ have to mention 
that 40-character function name in which you fixed something in your 
subject, then yeah, you'll go over the 50 chars.  But as recommendation 
the 50 chars make more sense than the 72 chars, IMHO.


Ciao,
Michael.
Segher Boessenkool Feb. 3, 2020, 6:56 p.m. | #24
On Mon, Feb 03, 2020 at 06:54:05PM +0100, Jakub Jelinek wrote:
> On Mon, Feb 03, 2020 at 05:48:57PM +0000, Michael Matz wrote:

> > On Mon, 3 Feb 2020, Richard Earnshaw (lists) wrote:

> > 

> > > The idea is that the [...] part is NOT part of the commit, only part of 

> > > the email.

> > 

> > I understand that, but the subject line of this thread says "e-mail 

> > subject lines", so I thought we were talking about, well, exactly that; 

> > and I see no value of these tags in e-mails either.

> 

> In email, they do carry information that is useful there, the distinction

> whether a patch has been committed already and doesn't need review from

> others, or whether it is a patch intended for patch review, or just a RFC

> patch that is not yet ready for review, but submitter is looking for some

> feedback.


It's irrelevant whether a patch is committed or not whather it needs
review, imnsho :-)

"rfc" is useful, certainly.  It makes clear that the sender would like
some help, and/or that the subject might be controversial, both things
that have more time pressure than most.


Segher
Segher Boessenkool Feb. 3, 2020, 7:47 p.m. | #25
On Mon, Feb 03, 2020 at 06:20:20PM +0000, Michael Matz wrote:
> On Mon, 3 Feb 2020, Richard Earnshaw (lists) wrote:

> > Well, I'd review a patch differently depending on whether or not it was 

> > already committed, a patch requiring review or an RFC looking for more 

> > general comments, so I *do* think such an email prefix is useful.

> 

> As I said: a very good argument must be made; it might be that rfc falls 

> into the useful-tag category.


Yes, "rfc" can be useful to know *before* reading the mail.

> > The 50 char limit seems to come from wanting git log --oneline to not wrap in

> > an 80 column terminal.  Whilst laudable, I'm not sure that such a limit

> > doesn't become too restrictive and then lead to hard-to-understand summaries.

> 

> In my experience hard-to-understand summaries are more related to people 

> writing them than to length, IOW, I fear a larger limit like 72 characters 

> won't help that.


Yup.  If it helps, don't think of it as "summary", think of it as "title".


Segher
Andrew Stubbs Feb. 4, 2020, 10:41 a.m. | #26
On 03/02/2020 18:09, Michael Matz wrote:
> But suggesting that using the subject line for tagging is recommended can

> lead to subjects like

> 

>   [PATCH][GCC][Foo][component] Fix foo component bootstrap failure

> 

> in an e-mail directed to gcc-patches@gcc.gnu.org (from somewhen last year,

> where Foo/foo was an architecture; I'm really not trying to single out the

> author).  That is, _none_ of the four tags carried any informational

> content.


I partially disagree with this. Certainly there's pointless redundancy 
it this example, but I'd rather have the tags with a meaningful subject 
than a generic subject with no tags.

gcc-patches is a high-volume list in which most of the content is 
outside my range of interest and/or understanding. If I stay on top of 
it then I can read all the subject lines, at least, and probably select 
a few threads to learn about something new, but if I let the list get 
away from me for even a short while then it's too much to handle.

I do have filters set up to highlight subjects for which I should pay 
attention and if people are in the habit of tagging subjects then that 
becomes much more reliable.

Conversely, the tags help me quickly decide what not to read.

I see that some people are using a "[email tag] git tag: msg" format, 
and I quite like that.

Andrew
Nathan Sidwell Feb. 27, 2020, 1:37 p.m. | #27
On 2/3/20 6:41 AM, Richard Earnshaw (lists) wrote:
> On 22/01/2020 17:45, Richard Earnshaw (lists) wrote:

>>

>> [updated based on v2 discussions]

>>

>> 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'.  Where

>> possible, I've tried to align these rules with those already in

>> use for glibc, so that the differences are minimal and only where

>> necessary.

>>

>> Some things that differ from existing practice (at least by some people)

>> are:

>>

>> - Use '<topic>:' rather than '[<topic>]'

>>    - This is more git friendly and works with 'git am'.

>> - Put bug numbers at the end of the line rather than the beginning.

>>    - The bug number is useful, but not as useful as the brief summary.

>>      Also, use the shortened form, as the topic part is more usefully

>>      conveyed in the proper topic field (see above).

> 

> I've not seen any follow-up to this version.  Should we go ahead and 

> adopt this?


do it!

do it! do it! do it!

nathan
-- 
Nathan Sidwell
Richard Earnshaw (lists) March 2, 2020, 1:01 p.m. | #28
On 27/02/2020 13:37, Nathan Sidwell wrote:
> On 2/3/20 6:41 AM, Richard Earnshaw (lists) wrote:

>> On 22/01/2020 17:45, Richard Earnshaw (lists) wrote:

>>>

>>> [updated based on v2 discussions]

>>>

>>> 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'.  Where

>>> possible, I've tried to align these rules with those already in

>>> use for glibc, so that the differences are minimal and only where

>>> necessary.

>>>

>>> Some things that differ from existing practice (at least by some people)

>>> are:

>>>

>>> - Use '<topic>:' rather than '[<topic>]'

>>>    - This is more git friendly and works with 'git am'.

>>> - Put bug numbers at the end of the line rather than the beginning.

>>>    - The bug number is useful, but not as useful as the brief summary.

>>>      Also, use the shortened form, as the topic part is more usefully

>>>      conveyed in the proper topic field (see above).

>>

>> I've not seen any follow-up to this version.  Should we go ahead and 

>> adopt this?

> 

> do it!

> 

> do it! do it! do it!

> 

> nathan


:-)

I'd like to.  But have we reached consensus?  Seems that every time I 
produce a revised version of the text we end up in another round of bike 
shedding.  (Is that a word?)

R.
Segher Boessenkool March 2, 2020, 1:34 p.m. | #29
On Mon, Mar 02, 2020 at 01:01:46PM +0000, Richard Earnshaw (lists) wrote:
> I'd like to.  But have we reached consensus?  Seems that every time I 

> produce a revised version of the text we end up in another round of bike 

> shedding.  (Is that a word?)


It's called a "lap", but "criterium" would be more suitable here.


Segher
Nathan Sidwell March 2, 2020, 2:31 p.m. | #30
On 3/2/20 8:01 AM, Richard Earnshaw (lists) wrote:
> On 27/02/2020 13:37, Nathan Sidwell wrote:

>> On 2/3/20 6:41 AM, Richard Earnshaw (lists) wrote:

>>> On 22/01/2020 17:45, Richard Earnshaw (lists) wrote:

>>>>

>>>> [updated based on v2 discussions]

>>>>

>>>> 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'.  Where

>>>> possible, I've tried to align these rules with those already in

>>>> use for glibc, so that the differences are minimal and only where

>>>> necessary.

>>>>

>>>> Some things that differ from existing practice (at least by some 

>>>> people)

>>>> are:

>>>>

>>>> - Use '<topic>:' rather than '[<topic>]'

>>>>    - This is more git friendly and works with 'git am'.

>>>> - Put bug numbers at the end of the line rather than the beginning.

>>>>    - The bug number is useful, but not as useful as the brief summary.

>>>>      Also, use the shortened form, as the topic part is more usefully

>>>>      conveyed in the proper topic field (see above).

>>>

>>> I've not seen any follow-up to this version.  Should we go ahead and 

>>> adopt this?


> I'd like to.  But have we reached consensus?  Seems that every time I 

> produce a revised version of the text we end up in another round of bike 

> shedding.  (Is that a word?)


I'm not sure I've seen a specific proposal following yours.  Some 
suggestions for differences, with varying degrees of forcefulness.  I 
still say go for it.

nathan

-- 
Nathan Sidwell
Jonathan Wakely March 2, 2020, 2:41 p.m. | #31
On Mon, 2 Mar 2020 at 14:31, Nathan Sidwell <nathan@acm.org> wrote:
>

> On 3/2/20 8:01 AM, Richard Earnshaw (lists) wrote:

> > On 27/02/2020 13:37, Nathan Sidwell wrote:

> >> On 2/3/20 6:41 AM, Richard Earnshaw (lists) wrote:

> >>> On 22/01/2020 17:45, Richard Earnshaw (lists) wrote:

> >>>>

> >>>> [updated based on v2 discussions]

> >>>>

> >>>> 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'.  Where

> >>>> possible, I've tried to align these rules with those already in

> >>>> use for glibc, so that the differences are minimal and only where

> >>>> necessary.

> >>>>

> >>>> Some things that differ from existing practice (at least by some

> >>>> people)

> >>>> are:

> >>>>

> >>>> - Use '<topic>:' rather than '[<topic>]'

> >>>>    - This is more git friendly and works with 'git am'.

> >>>> - Put bug numbers at the end of the line rather than the beginning.

> >>>>    - The bug number is useful, but not as useful as the brief summary.

> >>>>      Also, use the shortened form, as the topic part is more usefully

> >>>>      conveyed in the proper topic field (see above).

> >>>

> >>> I've not seen any follow-up to this version.  Should we go ahead and

> >>> adopt this?

>

> > I'd like to.  But have we reached consensus?  Seems that every time I

> > produce a revised version of the text we end up in another round of bike

> > shedding.  (Is that a word?)

>

> I'm not sure I've seen a specific proposal following yours.  Some

> suggestions for differences, with varying degrees of forcefulness.  I

> still say go for it.


Go for it.

It's not like we're going to take away commit privs from people who
use slight variations on the scheme. It's better to have a written
policy that people should aim towards, and most people will follow in
most cases.
Richard Earnshaw (lists) March 2, 2020, 3:22 p.m. | #32
On 02/03/2020 14:41, Jonathan Wakely wrote:
> On Mon, 2 Mar 2020 at 14:31, Nathan Sidwell <nathan@acm.org> wrote:

>>

>> On 3/2/20 8:01 AM, Richard Earnshaw (lists) wrote:

>>> On 27/02/2020 13:37, Nathan Sidwell wrote:

>>>> On 2/3/20 6:41 AM, Richard Earnshaw (lists) wrote:

>>>>> On 22/01/2020 17:45, Richard Earnshaw (lists) wrote:

>>>>>>

>>>>>> [updated based on v2 discussions]

>>>>>>

>>>>>> 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'.  Where

>>>>>> possible, I've tried to align these rules with those already in

>>>>>> use for glibc, so that the differences are minimal and only where

>>>>>> necessary.

>>>>>>

>>>>>> Some things that differ from existing practice (at least by some

>>>>>> people)

>>>>>> are:

>>>>>>

>>>>>> - Use '<topic>:' rather than '[<topic>]'

>>>>>>     - This is more git friendly and works with 'git am'.

>>>>>> - Put bug numbers at the end of the line rather than the beginning.

>>>>>>     - The bug number is useful, but not as useful as the brief summary.

>>>>>>       Also, use the shortened form, as the topic part is more usefully

>>>>>>       conveyed in the proper topic field (see above).

>>>>>

>>>>> I've not seen any follow-up to this version.  Should we go ahead and

>>>>> adopt this?

>>

>>> I'd like to.  But have we reached consensus?  Seems that every time I

>>> produce a revised version of the text we end up in another round of bike

>>> shedding.  (Is that a word?)

>>

>> I'm not sure I've seen a specific proposal following yours.  Some

>> suggestions for differences, with varying degrees of forcefulness.  I

>> still say go for it.

> 

> Go for it.

> 

> It's not like we're going to take away commit privs from people who

> use slight variations on the scheme. It's better to have a written

> policy that people should aim towards, and most people will follow in

> most cases.

> 


OK, pushed.   Folk can, of course, now propose changes to the text as it 
stands...

R.

Patch

diff --git a/htdocs/contribute.html b/htdocs/contribute.html
index 042ff069..558bae29 100644
--- a/htdocs/contribute.html
+++ b/htdocs/contribute.html
@@ -249,13 +249,143 @@  that ChangeLog entries may be included as part of the patch and diffs
 representing new files may be omitted, especially if large, since they
 can be accessed directly from the repository.)</p> 
 
+<h3>E-mail subject lines</h3>
+
+<p>Your contribution e-mail subject line will become the first line of
+the commit message for your patch.</p>
+
+<p>A high-quality e-mail subject line for a contribution contains the
+following elements:</p>
+
+<ul>
+  <li>A classifier</li>
+  <li>Component tags</li>
+  <li>An optional series identifier</li>
+  <li>A brief summary</li>
+  <li>An optional bug number</li>
+</ul>
+
+<p>The entire line (excluding the classifier) should not exceed 75
+characters.</p>
+
+<h4>Classifier</h4>
+
+<p>The classifier identifies the type of contribution, for example a
+patch, an RFC (request for comments) or a committed patch (where
+approval is not necessary.  The classifier should be written in upper
+case and surrounded with square brackets.  This is the only component
+of the e-mail subject line that will not appear in the commit itself.
+The classifier may optionally contain a version number (v<i>N</i>) and
+a series marker (<i>N/M</i>).  Examples are:</p>
+
+<ul>
+  <li><code>[PATCH]</code> - a single patch</li>
+  <li><code>[PATCH v2]</code> - the second version of a single patch</li>
+  <li><code>[PATCH 3/7]</code> - the third patch in a series of seven
+    patches</li>
+  <li><code>[RFC]</code> - a point of discussion, may contain a patch</li>
+  <li><code>[COMMITTED]</code> - a patch that has already been committed.</li>
+</ul>
+
+<h4>Component tags</h4>
+
+<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.  For example,</p>
+
+<ul>
+  <li><code>libstdc++:</code></li>
+  <li><code>combine:</code></li>
+  <li><code>vax: testsuite:</code></li>
+</ul>
+
+<p>Some large components may be subdivided into sub-components.  If
+the subcomponent name is not disctinct in its own right, you can use the
+form <i>component/sub-component:</i>.</p>
+
+<h4>Series identifier</h4>
+
+<p>The series identifier is optional and is only relevant if a number of
+patches are needed in order to effect an overall change.  It should be
+a <i>short</i> string that identifies the series (it is common to all
+patches) and should be followed by a single dash surrounded by white
+space.</p>
+
+<h4>A Very Brief summary</h4>
+
+<p>The brief summary encapsulates in a few words the intent of the
+change.  For example: <code>cleanup check_field_decls</code>.
+Although, very short, the summary should be distinct so that it will
+not be confused with other patches.</p>
+
+<h4>Bug number</h4>
+
+<p>If your patch relates a bug in the compiler for which there is an
+existing PR number the bug number should be stated.  Use the
+short-form variant <code>[PR<i>nnnnn</i>]</code> without the bugzilla
+component identifier and with no space between 'PR' and the number.
+The body of the commit message should still contain the full form
+(<code>PR &lt;component&gt;/<i>nnnnn</i></code>) within the body of
+the commit message so that Bugzilla will correctly notice the
+commit.  If your patch relates to two bugs, then write
+<code>[PR<i>nnnnn</i>, PR<i>mmmmm</i>]</code>.  For multiple
+bugs, just cite the most relevant one in the summary and use an
+elipsis instead of the second, or subsequent PR numbers; list all the
+related PRs in the body of the commit message in the normal way.</p>
+
+<p>It is not necessary to cite bugs that are closed as duplicates of
+another unless there is something specific to that report that
+is not covered by the parent bug.</p>
+
+<h4>Other messages</h4>
+
+<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.  The convention is
+that such messages should follow the same format as described above,
+but the patch number should be set to zero, for example: <code>[PATCH
+0/7]</code>.  Remember that the introductory message will not be
+committed with the patches themselves, so it should not contain any
+important information that is not also covered in the individual
+patches.  If you send a summary e-mail with a series it is a good idea
+to send the patches as follow-ups (essentially replies) to your
+initial message so that mail software can group the messages
+together.</p>
+
+<p>If you submit a new version of a patch series, then you should
+start a new email thread (don't reply to the original patch series).
+This avoids email threads becoming confused between discussions of the
+first and subsequent revisions of the patch set.  Your cover leter
+(0/<i>nnn</i>) should explain clearly what has been changed between
+the two patch series.  Also state if some of the patches are unchanged
+between revisions; this saves maintainers having to re-review the
+patches they might have already reviewed in an earlier version.  The
+individual patch messages should be as you expect them to be
+committed.  It is a good idea to send a final follow-up message to the
+original thread indicating that a new version has been submitted.</p>
+
+<h4>Examples</h4>
+
+<p>Here are some complete examples, based on real commits to GCC.</p>
+
+<ul>
+  <li><code>[COMMITTED] libstdc++: Fix freestanding build [PR92376]</code></li>
+  <li><code>[PATCH 1/6] analyzer: Fix tests for UNKNOWN_LOCATION</code></li>
+  <li><code>[RFC] doc: Note that some warnings depend on optimizations [PR92757]</code></li>
+  <li><code>[COMMITTED] c++: coroutines - Initial implementation</code></li>
+  <li><code>[PATCH v2] wwwdocs: E-mail subject lines for contributions</code></li>
+</ul>
+
 <h3>Pinging patches, Getting patches applied</h3>
 
 <p>If you do not receive a response to a patch that you have submitted
 within two weeks or so, it may be a good idea to chase it by sending a
-follow-up email to the same list(s).  Patches can occasionally fall through
-the cracks.  Please be sure to include a brief summary of the patch and the
-URL of the entry in the mailing list archive of the original submission.</p>
+follow-up e-mail to the same list(s).  Patches can occasionally fall
+through the cracks.  Please be sure to include a brief summary of the
+patch and the URL of the entry in the mailing list archive of the
+original submission.</p>
 
 <p>If you do not have write access and a patch of yours has been approved,
 but not committed, please advise the approver of that fact.  You may want