| Message ID | 91e48c52-4548-089b-707a-afd400001dac@arm.com |
|---|---|
| State | New |
| Headers | show |
| Series | [v3] wwwdocs: e-mail subject lines for contributions | expand |
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.
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
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.
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
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
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.
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
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.
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.
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.
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.
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
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
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
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.
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
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. >
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.
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
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.
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
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.
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.
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
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
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
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
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.
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
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
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.
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.
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 <component>/<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
[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).