[wwwdocs] Updates to contribute.html for git-friendly posting rules

[wwwdocs] Updates to contribute.html for git-friendly posting rules

[Richard Earnshaw (lists)]

[-- Attachment #1: Type: text/plain, Size: 402 bytes --]

The thread on gcc@ is now so long and complicated that this proposal 
back at the start has dropped off the radar.  With the switch now 
imminent I'd like to re-propose this change, this time more formally.

The text below draws heavily on the glibc equivalent rules in an attempt 
to bring some harmony, but it inevitably has some local customizations 
because these aren't the same project.

OK?

R.

[-- Attachment #2: contribute.patch --]
[-- Type: text/x-patch, Size: 3727 bytes --]

diff --git a/htdocs/contribute.html b/htdocs/contribute.html
index 381aa02a..99d5b73e 100644
--- a/htdocs/contribute.html
+++ b/htdocs/contribute.html
@@ -262,6 +262,89 @@ 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>Email subject lines</h3>
+
+Your contribution email subject line will become the first line of the
+commit message for your patch.
+
+A high-quality email subject line for a contribution contains the
+following elements:
+
+<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>
+
+<h4>Classifier</h4>
+
+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 email 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:
+
+<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>
+
+A component tag is a short identifier that identifies the part of the
+compiler being modified, this is important as it highlights to
+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,
+
+<ul>
+  <li><code>vax: testsuite:</code></li>
+  <li><code>libstdc++:</code></li>
+  <li><code>combine:</code></li>
+</ul>
+
+<h4>Series identifier</h4>
+
+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.
+
+<h4>Brief summary</h4>
+
+The brief summary encapsulates in a few words the intent of the
+change.  For example: <code>cleanup check_field_decls</code>.
+
+<h4>Bug number</h4>
+
+If your patch fixes a bug in the compiler for which there is an
+existing PR number the bug number should be stated.  Use the
+short-form variant (PR<i>nnnnn</i>) without the bugzilla component
+identifier.
+
+<h4>Other messages</h4>
+
+Some large patch sets benefit from an introductory email 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 email 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.
+
 <h3>Pinging patches, Getting patches applied</h3>
 
 <p>If you do not receive a response to a patch that you have submitted

Re: [wwwdocs] Updates to contribute.html for git-friendly posting rules

[Gerald Pfeifer]

Hi Richard,

On Thu, 9 Jan 2020, Richard Earnshaw (lists) wrote:
> The thread on gcc@ is now so long and complicated that this proposal 
> back at the start has dropped off the radar.  With the switch now 
> imminent I'd like to re-propose this change, this time more formally.

I wasn't sure *who* would best approve this since it's more a policy
question than anything else, but let's unstall this...


There's a general note I'd make, partly based on my going through
some of our older web contents recently (and "decluttering" some 
of it), and some specific feedback.


The general note is that we've had a tendency to be very specific 
in some of our policies (see the last hunk of 
https://gcc.gnu.org/ml/gcc-patches/2020-01/msg01064.html for an 
example) which can make appear us not very inviting to new blood.

That is, if all I wanted is to submit a simple patch for a typo
somewhere, how would I feel about our set of instructions, and
now this addition? 

Is there a way to make this more light weight or less complex/
optional for simple contributions?


+<h3>Email subject lines</h3>

If I interpret both Merriam-Webster and the OED correctly, "e-mail"
is the preferrable spelling?

+Your contribution email subject line will become the first line of the
+commit message for your patch.

<p> ... </p> around paragraphs (throughout).

+<h4>Classifier</h4>
+
+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 email 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:
+
+<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>

I see a lot of [C++], [aarch64], [fortran], [wwwdocs] ;-),... in
our archives.

Should this all really move into the remainder of the subject line/
first line of the commit message?  I guess this is a key part change
as part of your proposal?

+<h4>Component tags</h4>

Alternately we could use [PATCH,fortran], [committed,C++],... ?


Actually, if we use PATCH, RFC,... for everything else, could
COMMITTED be omitted?  That feels like a bit of shouting (so if
we keep that, at least make it lower case)?


+A component tag is a short identifier that identifies the part of the
+compiler being modified, this is important as it highlights to

Full stop: "...modified. This is..." or, better "...modified. This
highlights..." which is shorter.


I believe this could benefit from some examples of overall subject
lines.  In fact, perhaps start with examples and describe the individual
components?


As for next steps, can you please mail the (updated) proposal to
the gcc@ list?  Some, even quite prominent contributors, do not
follow gcc-patches at all (or not close) and this is bigger policy 
question that will be interesting to the broad group.

Hope this helps,
Gerald

Re: [wwwdocs] Updates to contribute.html for git-friendly posting rules

[Richard Earnshaw (lists)]

On 19/01/2020 14:09, Gerald Pfeifer wrote:
> Hi Richard,
> 
> On Thu, 9 Jan 2020, Richard Earnshaw (lists) wrote:
>> The thread on gcc@ is now so long and complicated that this proposal
>> back at the start has dropped off the radar.  With the switch now
>> imminent I'd like to re-propose this change, this time more formally.
> 
> I wasn't sure *who* would best approve this since it's more a policy
> question than anything else, but let's unstall this...
> 
> 
> There's a general note I'd make, partly based on my going through
> some of our older web contents recently (and "decluttering" some
> of it), and some specific feedback.
> 
> 
> The general note is that we've had a tendency to be very specific
> in some of our policies (see the last hunk of
> https://gcc.gnu.org/ml/gcc-patches/2020-01/msg01064.html for an
> example) which can make appear us not very inviting to new blood.
> 
> That is, if all I wanted is to submit a simple patch for a typo
> somewhere, how would I feel about our set of instructions, and
> now this addition?
> 
> Is there a way to make this more light weight or less complex/
> optional for simple contributions?

The more we make the process lightweight for contributors, the more work 
we make for maintainers.  If the contribution is sent correctly, then 
ideally, the patch can be applied with just 'git am' by the maintainer. 
So while we shouldn't overburden things, we shouldn't go too far.  I 
don't think we've added anything that glibc don't already require, for 
example, or many other git-based development communities.

> 
> 
> +<h3>Email subject lines</h3>
> 
> If I interpret both Merriam-Webster and the OED correctly, "e-mail"
> is the preferrable spelling?
> 
> +Your contribution email subject line will become the first line of the
> +commit message for your patch.
> 

Changed - I note that there are some other uses of 'email' on the web 
pages.  I'm not fixing those.

> <p> ... </p> around paragraphs (throughout).
> 

Done.

> +<h4>Classifier</h4>
> +
> +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 email 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:
> +
> +<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>
> 
> I see a lot of [C++], [aarch64], [fortran], [wwwdocs] ;-),... in
> our archives.

the [] annotation makes life harder for 'git am' as it automatically 
strips such prefixes when applying the patch.  'git am --keep-non-patch' 
can avoid stripping such tags, but it's a bit of a mouthful to keep 
typing it.  Git communities (including glibc) generally use <topic>: 
these days, so this aligns with that.
> 
> Should this all really move into the remainder of the subject line/
> first line of the commit message?  I guess this is a key part change
> as part of your proposal?
> 

The point is to get a good, concise summary that appears in "git log 
--oneline" showing the history of commits.  Moving it to the body breaks 
that.

> +<h4>Component tags</h4>
> 
> Alternately we could use [PATCH,fortran], [committed,C++],... ?
> 

Please, no.  See comment about stripping above.

> 
> Actually, if we use PATCH, RFC,... for everything else, could
> COMMITTED be omitted?  That feels like a bit of shouting (so if
> we keep that, at least make it lower case)?
> 

This is about consistency across the communities that use git.

> 
> +A component tag is a short identifier that identifies the part of the
> +compiler being modified, this is important as it highlights to
> 
> Full stop: "...modified. This is..." or, better "...modified. This
> highlights..." which is shorter.
> 

Fixed.

> 
> I believe this could benefit from some examples of overall subject
> lines.  In fact, perhaps start with examples and describe the individual
> components?
> 
> 
> As for next steps, can you please mail the (updated) proposal to
> the gcc@ list?  Some, even quite prominent contributors, do not
> follow gcc-patches at all (or not close) and this is bigger policy
> question that will be interesting to the broad group.
> 

I sent the proposal to gcc@ last year on the basis that this was policy 
rather than a simple technical change, but it didn't make any progress 
(the thread got rather bogged down with other unrelated discussions). 
Anyway, patches are supposed to go to gcc-patches, even for the web 
pages, aren't they?

I'll send the update to both lists...

R.

> Hope this helps,
> Gerald
> 

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

[Richard Earnshaw (lists)]

[-- Attachment #1: Type: text/plain, Size: 1000 bytes --]

[updated, following some comments from Gerald, main differences are
  slight tweaks to the html markup and changing "email" to "e-mail"]

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



[-- Attachment #2: contrib.patch --]
[-- Type: text/x-patch, Size: 4469 bytes --]

diff --git a/htdocs/contribute.html b/htdocs/contribute.html
index 042ff069..861f7e5e 100644
--- a/htdocs/contribute.html
+++ b/htdocs/contribute.html
@@ -249,13 +249,98 @@ 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>
+
+<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>
+
+<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>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>.</p>
+
+<h4>Bug number</h4>
+
+<p>If your patch fixes a bug in the compiler for which there is an
+existing PR number the bug number should be stated.  Use the
+short-form variant (PR<i>nnnnn</i>) without the bugzilla component
+identifier.</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>
+
 <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

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

[Jakub Jelinek]

On Tue, Jan 21, 2020 at 02:52:00PM +0000, Richard Earnshaw (lists) wrote:
> [updated, following some comments from Gerald, main differences are
>  slight tweaks to the html markup and changing "email" to "e-mail"]
> 
> 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).

Some examples would be useful I'd say, e.g. it is unclear in what way you
want the PR number to be appended, shall it be
something: whatever words describe it PR12345
or
something: whatever words describe it (PR12345)
or
something: whatever words describe it: PR12345
or
something: whatever words describe it [PR12345]
or something else?

Also, it would be nice to stress that the PR long form should be in the
ChangeLog and somewhere on the later lines of the commit message, I don't
think we pick up the shorter form from the first line when it short form (I
could be wrong, but e.g.
https://gcc.gnu.org/g:865257c447cc50f5819e9b53da83145f3c36c305
commit didn't make it into bugzilla).

	Jakub

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

[Richard Earnshaw (lists)]

On 21/01/2020 15:04, Jakub Jelinek wrote:
> On Tue, Jan 21, 2020 at 02:52:00PM +0000, Richard Earnshaw (lists) wrote:
>> [updated, following some comments from Gerald, main differences are
>>   slight tweaks to the html markup and changing "email" to "e-mail"]
>>
>> 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).
> 
> Some examples would be useful I'd say, e.g. it is unclear in what way you
> want the PR number to be appended, shall it be
> something: whatever words describe it PR12345
> or
> something: whatever words describe it (PR12345)
> or
> something: whatever words describe it: PR12345
> or
> something: whatever words describe it [PR12345]
> or something else?

Glibc use "[BZ #nnnn]" - obviously BZ becomes PR, but after that, I'm 
not too worried.  I'd be happy with [PR #nnnn], but if folk want 
something else, please say so quickly...

I'll prepare an edit for that...

> 
> Also, it would be nice to stress that the PR long form should be in the
> ChangeLog and somewhere on the later lines of the commit message, I don't
> think we pick up the shorter form from the first line when it short form (I
> could be wrong, but e.g.
> https://gcc.gnu.org/g:865257c447cc50f5819e9b53da83145f3c36c305
> commit didn't make it into bugzilla).
> 

Yes, good point.

Thanks.

R.

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

[Jakub Jelinek]

On Tue, Jan 21, 2020 at 03:33:22PM +0000, Richard Earnshaw (lists) wrote:
> > Some examples would be useful I'd say, e.g. it is unclear in what way you
> > want the PR number to be appended, shall it be
> > something: whatever words describe it PR12345
> > or
> > something: whatever words describe it (PR12345)
> > or
> > something: whatever words describe it: PR12345
> > or
> > something: whatever words describe it [PR12345]
> > or something else?
> 
> Glibc use "[BZ #nnnn]" - obviously BZ becomes PR, but after that, I'm not
> too worried.  I'd be happy with [PR #nnnn], but if folk want something else,
> please say so quickly...

[PR 12345] or [PR #12345] is bad, because the bugzilla won't underline it,
it needs to be either PR12345 word, or PR component/12345 .

	Jakub

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

[Richard Earnshaw (lists)]

On 21/01/2020 15:39, Jakub Jelinek wrote:
> On Tue, Jan 21, 2020 at 03:33:22PM +0000, Richard Earnshaw (lists) wrote:
>>> Some examples would be useful I'd say, e.g. it is unclear in what way you
>>> want the PR number to be appended, shall it be
>>> something: whatever words describe it PR12345
>>> or
>>> something: whatever words describe it (PR12345)
>>> or
>>> something: whatever words describe it: PR12345
>>> or
>>> something: whatever words describe it [PR12345]
>>> or something else?
>>
>> Glibc use "[BZ #nnnn]" - obviously BZ becomes PR, but after that, I'm not
>> too worried.  I'd be happy with [PR #nnnn], but if folk want something else,
>> please say so quickly...
> 
> [PR 12345] or [PR #12345] is bad, because the bugzilla won't underline it,
> it needs to be either PR12345 word, or PR component/12345 .
> 
> 	Jakub
> 

ok, lets go with [PRnnnn] then.

R.

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

[Jason Merrill]

On 1/21/20 10:40 AM, Richard Earnshaw (lists) wrote:
> On 21/01/2020 15:39, Jakub Jelinek wrote:
>> On Tue, Jan 21, 2020 at 03:33:22PM +0000, Richard Earnshaw (lists) wrote:
>>>> Some examples would be useful I'd say, e.g. it is unclear in what 
>>>> way you
>>>> want the PR number to be appended, shall it be
>>>> something: whatever words describe it PR12345
>>>> or
>>>> something: whatever words describe it (PR12345)
>>>> or
>>>> something: whatever words describe it: PR12345
>>>> or
>>>> something: whatever words describe it [PR12345]
>>>> or something else?
>>>
>>> Glibc use "[BZ #nnnn]" - obviously BZ becomes PR, but after that, I'm 
>>> not
>>> too worried.  I'd be happy with [PR #nnnn], but if folk want 
>>> something else,
>>> please say so quickly...
>>
>> [PR 12345] or [PR #12345] is bad, because the bugzilla won't underline 
>> it,
>> it needs to be either PR12345 word, or PR component/12345 .
> 
> ok, lets go with [PRnnnn] then.

Doesn't this use of [] have the same problem with git am?

My summaries are often describing the bug I'm fixing, i.e.

[PATCH] PR c++/91476 - anon-namespace reference temp clash between TUs.

which is also the first line of my ChangeLog entry.  I think you are 
proposing

[COMMITTED] c++: Fix anon-namespace reference temp clash between TUs 
(PR91476)

which can no longer be shared with the ChangeLog.

Jason

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

[Richard Earnshaw (lists)]

On 21/01/2020 17:20, Jason Merrill wrote:
> On 1/21/20 10:40 AM, Richard Earnshaw (lists) wrote:
>> On 21/01/2020 15:39, Jakub Jelinek wrote:
>>> On Tue, Jan 21, 2020 at 03:33:22PM +0000, Richard Earnshaw (lists) 
>>> wrote:
>>>>> Some examples would be useful I'd say, e.g. it is unclear in what 
>>>>> way you
>>>>> want the PR number to be appended, shall it be
>>>>> something: whatever words describe it PR12345
>>>>> or
>>>>> something: whatever words describe it (PR12345)
>>>>> or
>>>>> something: whatever words describe it: PR12345
>>>>> or
>>>>> something: whatever words describe it [PR12345]
>>>>> or something else?
>>>>
>>>> Glibc use "[BZ #nnnn]" - obviously BZ becomes PR, but after that, 
>>>> I'm not
>>>> too worried.  I'd be happy with [PR #nnnn], but if folk want 
>>>> something else,
>>>> please say so quickly...
>>>
>>> [PR 12345] or [PR #12345] is bad, because the bugzilla won't 
>>> underline it,
>>> it needs to be either PR12345 word, or PR component/12345 .
>>
>> ok, lets go with [PRnnnn] then.
> 
> Doesn't this use of [] have the same problem with git am?

No, because only 'leading' [] blocks are removed - git mailinfo --help

> 
> My summaries are often describing the bug I'm fixing, i.e.
> 
> [PATCH] PR c++/91476 - anon-namespace reference temp clash between TUs.
> 
> which is also the first line of my ChangeLog entry.  I think you are 
> proposing
> 
> [COMMITTED] c++: Fix anon-namespace reference temp clash between TUs 
> (PR91476)
> 
> which can no longer be shared with the ChangeLog.
> 

I was trying to unify this with glibc.  They specify the bug number at 
the end of the line.

We can diverge if it's generally felt to be important, but details like 
this create needless friction for folk working in both communities.

R.

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

[Jakub Jelinek]

On Tue, Jan 21, 2020 at 06:50:13PM +0000, Richard Earnshaw (lists) wrote:
> > Doesn't this use of [] have the same problem with git am?
> 
> No, because only 'leading' [] blocks are removed - git mailinfo --help

I've used
openmp: Teach omp_code_to_statement about rest of OpenMP statements [PR93329]
as the first line of a commit log and that [PR93329] part is completely gone
from it.

	Jakub

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

[Richard Earnshaw (lists)]

On 22/01/2020 09:07, Jakub Jelinek wrote:
> On Tue, Jan 21, 2020 at 06:50:13PM +0000, Richard Earnshaw (lists) wrote:
>>> Doesn't this use of [] have the same problem with git am?
>>
>> No, because only 'leading' [] blocks are removed - git mailinfo --help
> 
> I've used
> openmp: Teach omp_code_to_statement about rest of OpenMP statements [PR93329]
> as the first line of a commit log and that [PR93329] part is completely gone
> from it.
> 
> 	Jakub
> 

How did you apply the patch?

R.

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

[Jakub Jelinek]

On Wed, Jan 22, 2020 at 09:35:31AM +0000, Richard Earnshaw (lists) wrote:
> On 22/01/2020 09:07, Jakub Jelinek wrote:
> > On Tue, Jan 21, 2020 at 06:50:13PM +0000, Richard Earnshaw (lists) wrote:
> > > > Doesn't this use of [] have the same problem with git am?
> > > 
> > > No, because only 'leading' [] blocks are removed - git mailinfo --help
> > 
> > I've used
> > openmp: Teach omp_code_to_statement about rest of OpenMP statements [PR93329]
> > as the first line of a commit log and that [PR93329] part is completely gone
> > from it.
> 
> How did you apply the patch?

Just git commit -a and editing the log message.
But I got the [PR.....] not eaten in another commit, so ignore the above for
now (although I'm very much convinced it was in there when I wrote the
commit log).

	Jakub

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

[Richard Sandiford]

"Richard Earnshaw (lists)" <Richard.Earnshaw@arm.com> writes:
> On 21/01/2020 17:20, Jason Merrill wrote:
>> On 1/21/20 10:40 AM, Richard Earnshaw (lists) wrote:
>>> On 21/01/2020 15:39, Jakub Jelinek wrote:
>>>> On Tue, Jan 21, 2020 at 03:33:22PM +0000, Richard Earnshaw (lists) 
>>>> wrote:
>>>>>> Some examples would be useful I'd say, e.g. it is unclear in what 
>>>>>> way you
>>>>>> want the PR number to be appended, shall it be
>>>>>> something: whatever words describe it PR12345
>>>>>> or
>>>>>> something: whatever words describe it (PR12345)
>>>>>> or
>>>>>> something: whatever words describe it: PR12345
>>>>>> or
>>>>>> something: whatever words describe it [PR12345]
>>>>>> or something else?
>>>>>
>>>>> Glibc use "[BZ #nnnn]" - obviously BZ becomes PR, but after that, 
>>>>> I'm not
>>>>> too worried.  I'd be happy with [PR #nnnn], but if folk want 
>>>>> something else,
>>>>> please say so quickly...
>>>>
>>>> [PR 12345] or [PR #12345] is bad, because the bugzilla won't 
>>>> underline it,
>>>> it needs to be either PR12345 word, or PR component/12345 .
>>>
>>> ok, lets go with [PRnnnn] then.
>> 
>> Doesn't this use of [] have the same problem with git am?
>
> No, because only 'leading' [] blocks are removed - git mailinfo --help
>
>> 
>> My summaries are often describing the bug I'm fixing, i.e.
>> 
>> [PATCH] PR c++/91476 - anon-namespace reference temp clash between TUs.
>> 
>> which is also the first line of my ChangeLog entry.  I think you are 
>> proposing
>> 
>> [COMMITTED] c++: Fix anon-namespace reference temp clash between TUs 
>> (PR91476)
>> 
>> which can no longer be shared with the ChangeLog.
>> 
>
> I was trying to unify this with glibc.  They specify the bug number at 
> the end of the line.
>
> We can diverge if it's generally felt to be important, but details like 
> this create needless friction for folk working in both communities.

+1 for "component: Summary [PRnnnnn]" FWIW.

PR bz-component/nnnnn works well for C++.  The problem is that so many
other PRs come under tree-optimization and rtl-optimization, which
eat up a lot of subject line characters without narrowing things down
very much.  "cselib: ... [PRnnnnn]" is both shorter and more descriptive
than "PR rtl-optimization/nnnnn - ....", etc.

Same idea for "PR target/nnnnn - ...": you then need to say which target
you mean in the main summary, whereas "aarch64: .... [PRnnnnn]" makes
it easier to keep the main summary short.

Maybe that's just a problem with the bz classification though...

Richard

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

[Marek Polacek]

On Wed, Jan 22, 2020 at 04:05:37PM +0000, Richard Sandiford wrote:
> "Richard Earnshaw (lists)" <Richard.Earnshaw@arm.com> writes:
> > On 21/01/2020 17:20, Jason Merrill wrote:
> >> On 1/21/20 10:40 AM, Richard Earnshaw (lists) wrote:
> >>> On 21/01/2020 15:39, Jakub Jelinek wrote:
> >>>> On Tue, Jan 21, 2020 at 03:33:22PM +0000, Richard Earnshaw (lists) 
> >>>> wrote:
> >>>>>> Some examples would be useful I'd say, e.g. it is unclear in what 
> >>>>>> way you
> >>>>>> want the PR number to be appended, shall it be
> >>>>>> something: whatever words describe it PR12345
> >>>>>> or
> >>>>>> something: whatever words describe it (PR12345)
> >>>>>> or
> >>>>>> something: whatever words describe it: PR12345
> >>>>>> or
> >>>>>> something: whatever words describe it [PR12345]
> >>>>>> or something else?
> >>>>>
> >>>>> Glibc use "[BZ #nnnn]" - obviously BZ becomes PR, but after that, 
> >>>>> I'm not
> >>>>> too worried.  I'd be happy with [PR #nnnn], but if folk want 
> >>>>> something else,
> >>>>> please say so quickly...
> >>>>
> >>>> [PR 12345] or [PR #12345] is bad, because the bugzilla won't 
> >>>> underline it,
> >>>> it needs to be either PR12345 word, or PR component/12345 .
> >>>
> >>> ok, lets go with [PRnnnn] then.
> >> 
> >> Doesn't this use of [] have the same problem with git am?
> >
> > No, because only 'leading' [] blocks are removed - git mailinfo --help
> >
> >> 
> >> My summaries are often describing the bug I'm fixing, i.e.
> >> 
> >> [PATCH] PR c++/91476 - anon-namespace reference temp clash between TUs.
> >> 
> >> which is also the first line of my ChangeLog entry.  I think you are 
> >> proposing
> >> 
> >> [COMMITTED] c++: Fix anon-namespace reference temp clash between TUs 
> >> (PR91476)
> >> 
> >> which can no longer be shared with the ChangeLog.
> >> 
> >
> > I was trying to unify this with glibc.  They specify the bug number at 
> > the end of the line.
> >
> > We can diverge if it's generally felt to be important, but details like 
> > this create needless friction for folk working in both communities.
> 
> +1 for "component: Summary [PRnnnnn]" FWIW.
> 
> PR bz-component/nnnnn works well for C++.  The problem is that so many
> other PRs come under tree-optimization and rtl-optimization, which
> eat up a lot of subject line characters without narrowing things down
> very much.  "cselib: ... [PRnnnnn]" is both shorter and more descriptive
> than "PR rtl-optimization/nnnnn - ....", etc.

Yeah, the cselib version definitely looks preferable to me.

What if a patch touches more than just the C++ FE, do we want "c,c++:"?
Though kernel uses

net: sched: act_ctinfo: fix memory leak
locking/rwsem: Fix kernel crash when spinning on RWSEM_OWNER_UNKNOWN

If a patch touches various spots in the optimizers, maybe we can
just go with "tree-opt:" or "rtl:"?

Further, I suppose multiple PRs fixed by a single patch would look like:

c++: Implement DR 666 [PR57, PR12345]

Marek

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

[Richard Earnshaw (lists)]

On 22/01/2020 16:28, Marek Polacek wrote:
> On Wed, Jan 22, 2020 at 04:05:37PM +0000, Richard Sandiford wrote:
>> "Richard Earnshaw (lists)" <Richard.Earnshaw@arm.com> writes:
>>> On 21/01/2020 17:20, Jason Merrill wrote:
>>>> On 1/21/20 10:40 AM, Richard Earnshaw (lists) wrote:
>>>>> On 21/01/2020 15:39, Jakub Jelinek wrote:
>>>>>> On Tue, Jan 21, 2020 at 03:33:22PM +0000, Richard Earnshaw (lists)
>>>>>> wrote:
>>>>>>>> Some examples would be useful I'd say, e.g. it is unclear in what
>>>>>>>> way you
>>>>>>>> want the PR number to be appended, shall it be
>>>>>>>> something: whatever words describe it PR12345
>>>>>>>> or
>>>>>>>> something: whatever words describe it (PR12345)
>>>>>>>> or
>>>>>>>> something: whatever words describe it: PR12345
>>>>>>>> or
>>>>>>>> something: whatever words describe it [PR12345]
>>>>>>>> or something else?
>>>>>>>
>>>>>>> Glibc use "[BZ #nnnn]" - obviously BZ becomes PR, but after that,
>>>>>>> I'm not
>>>>>>> too worried.  I'd be happy with [PR #nnnn], but if folk want
>>>>>>> something else,
>>>>>>> please say so quickly...
>>>>>>
>>>>>> [PR 12345] or [PR #12345] is bad, because the bugzilla won't
>>>>>> underline it,
>>>>>> it needs to be either PR12345 word, or PR component/12345 .
>>>>>
>>>>> ok, lets go with [PRnnnn] then.
>>>>
>>>> Doesn't this use of [] have the same problem with git am?
>>>
>>> No, because only 'leading' [] blocks are removed - git mailinfo --help
>>>
>>>>
>>>> My summaries are often describing the bug I'm fixing, i.e.
>>>>
>>>> [PATCH] PR c++/91476 - anon-namespace reference temp clash between TUs.
>>>>
>>>> which is also the first line of my ChangeLog entry.  I think you are
>>>> proposing
>>>>
>>>> [COMMITTED] c++: Fix anon-namespace reference temp clash between TUs
>>>> (PR91476)
>>>>
>>>> which can no longer be shared with the ChangeLog.
>>>>
>>>
>>> I was trying to unify this with glibc.  They specify the bug number at
>>> the end of the line.
>>>
>>> We can diverge if it's generally felt to be important, but details like
>>> this create needless friction for folk working in both communities.
>>
>> +1 for "component: Summary [PRnnnnn]" FWIW.
>>
>> PR bz-component/nnnnn works well for C++.  The problem is that so many
>> other PRs come under tree-optimization and rtl-optimization, which
>> eat up a lot of subject line characters without narrowing things down
>> very much.  "cselib: ... [PRnnnnn]" is both shorter and more descriptive
>> than "PR rtl-optimization/nnnnn - ....", etc.
> 
> Yeah, the cselib version definitely looks preferable to me.
> 
> What if a patch touches more than just the C++ FE, do we want "c,c++:"?

c-common: or c-family:?

> Though kernel uses
> 
> net: sched: act_ctinfo: fix memory leak

I'd read that as a patch that crosses the three separate components.

> locking/rwsem: Fix kernel crash when spinning on RWSEM_OWNER_UNKNOWN

And this would be a patch that affectst the rwsem sub-component of locking.

> 
> If a patch touches various spots in the optimizers, maybe we can
> just go with "tree-opt:" or "rtl:"?
> 

Not sure we want to get that prescriptive.  Things are likely to change 
around anyway.  rtl: would suggest it was one of the non-specific 
rtl-related issues, tree: similarly for a tree-related issue.

> Further, I suppose multiple PRs fixed by a single patch would look like:
> 
> c++: Implement DR 666 [PR57, PR12345]

Depends on the overall context.  In the subject line I think it would be 
acceptable to reference just one, perhaps two PRs.  If there are more, 
then something like
[PRnnn, ...]

would probably be an acceptable way of showing that more were referenced 
later in the body.
> 
> Marek
> 

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

[Segher Boessenkool]

Hi!

Thanks for doing this.

On Tue, Jan 21, 2020 at 02:52:00PM +0000, Richard Earnshaw (lists) wrote:
> This patch proposes some new (additional) rules for email subject lines
> when contributing to GCC.  The goal is to make sure that, as far as
> possible, the subject for a patch will form a good summary when the
> message is committed to the repository if applied with 'git am'.

> +<p>A high-quality e-mail subject line for a contribution contains the
> +following elements:</p>

> +  <li>A brief summary</li>

You could stress that this is the one thing that really matters.  And
it's not a summary, it's much too brief for that (at most ~50 chars),
but yup it should be something that allows *a human* to identify what
this is.

Everything else is just convention.

> +<p>A component tag is a short identifier that identifies the part of
> +the compiler being modified.  This highlights to the relevant
> +maintainers that the patch may need their attention.  Multiple
> +components may be listed if necessary.  Each component tag should be
> +followed by a colon.

Often people use aaa/bbb: if drilling down a bit that way helps keep the
subject short (which is the *point* of all this: keep things better
consumable for humans).

> +<p>The brief summary encapsulates in a few words the intent of the
> +change.  For example: <code>cleanup check_field_decls</code>.</p>

It should start with a capital though.  "Clean up blablal".  (So no
dot to end the sentence, this isn't a sentence).  A capital helps
the reader to quickly identify what is what, separate fluff from the
core parts.

> +<p>Some large patch sets benefit from an introductory e-mail that
> +provides more context for the patch series and describes how the
> +patches have been broken up to provide for review.

All non-trivial series, yeah.

Maybe we should mention how v2 etc. of patch series should show what is
changed?  If there is a good standard practice for that at all :-)


Segher

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

[Richard Earnshaw (lists)]

On 21/01/2020 19:26, Segher Boessenkool wrote:
> Hi!
> 
> Thanks for doing this.
> 
> On Tue, Jan 21, 2020 at 02:52:00PM +0000, Richard Earnshaw (lists) wrote:
>> This patch proposes some new (additional) rules for email subject lines
>> when contributing to GCC.  The goal is to make sure that, as far as
>> possible, the subject for a patch will form a good summary when the
>> message is committed to the repository if applied with 'git am'.
> 
>> +<p>A high-quality e-mail subject line for a contribution contains the
>> +following elements:</p>
> 
>> +  <li>A brief summary</li>
> 
> You could stress that this is the one thing that really matters.  And
> it's not a summary, it's much too brief for that (at most ~50 chars),
> but yup it should be something that allows *a human* to identify what
> this is.
> 

Well, it should all matter, or why are we requiring it?

I'm happy to insert 'very' in front of 'brief' and to say elsewhere that 
the entire subject (less the leading [...] part, should rarely, if ever, 
go beyond 80 characters.

> Everything else is just convention.
> 
>> +<p>A component tag is a short identifier that identifies the part of
>> +the compiler being modified.  This highlights to the relevant
>> +maintainers that the patch may need their attention.  Multiple
>> +components may be listed if necessary.  Each component tag should be
>> +followed by a colon.
> 
> Often people use aaa/bbb: if drilling down a bit that way helps keep the
> subject short (which is the *point* of all this: keep things better
> consumable for humans).

The aaa: bbb: is really for when aaa and bbb are independent parts of 
the compiler and potentially needs multiple reviewers. aaa/bbb is when 
bbb is strictly a sub-component of aaa (for example, arm/SVE: would be 
an SVE related issue in the arm backend).  I'm certainly not against 
having that.

> 
>> +<p>The brief summary encapsulates in a few words the intent of the
>> +change.  For example: <code>cleanup check_field_decls</code>.</p>
> 
> It should start with a capital though.  "Clean up blablal".  (So no
> dot to end the sentence, this isn't a sentence).  A capital helps
> the reader to quickly identify what is what, separate fluff from the
> core parts.
> 

There is a balance here to be made.  I'm mindful of Gerald's concern 
that this is perhaps overly restrictive for new users already.  I 
certainly think we should have a good house style, but getting too 
prescriptive just gets in the way of attracting good contributions.

>> +<p>Some large patch sets benefit from an introductory e-mail that
>> +provides more context for the patch series and describes how the
>> +patches have been broken up to provide for review.
> 
> All non-trivial series, yeah.
> 
> Maybe we should mention how v2 etc. of patch series should show what is
> changed?  If there is a good standard practice for that at all :-)
> 

Dunno.  I think that belongs primarily in the v2 0/n mail.  It's not, 
after all, something that needs to be kept once the patches are applied.

R.
> 
> Segher
> 

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

[Segher Boessenkool]

On Wed, Jan 22, 2020 at 10:00:00AM +0000, Richard Earnshaw (lists) wrote:
> On 21/01/2020 19:26, Segher Boessenkool wrote:
> >On Tue, Jan 21, 2020 at 02:52:00PM +0000, Richard Earnshaw (lists) wrote:
> >>+  <li>A brief summary</li>
> >
> >You could stress that this is the one thing that really matters.  And
> >it's not a summary, it's much too brief for that (at most ~50 chars),
> >but yup it should be something that allows *a human* to identify what
> >this is.
> >
> 
> Well, it should all matter, or why are we requiring it?

Yes.

> I'm happy to insert 'very' in front of 'brief' and to say elsewhere that 
> the entire subject (less the leading [...] part, should rarely, if ever, 
> go beyond 80 characters.

The usual recommendation is 50 chars.   Which is just about right with
most MUAs.

> >Everything else is just convention.
> >
> >>+<p>A component tag is a short identifier that identifies the part of
> >>+the compiler being modified.  This highlights to the relevant
> >>+maintainers that the patch may need their attention.  Multiple
> >>+components may be listed if necessary.  Each component tag should be
> >>+followed by a colon.
> >
> >Often people use aaa/bbb: if drilling down a bit that way helps keep the
> >subject short (which is the *point* of all this: keep things better
> >consumable for humans).
> 
> The aaa: bbb: is really for when aaa and bbb are independent parts of 
> the compiler and potentially needs multiple reviewers. aaa/bbb is when 
> bbb is strictly a sub-component of aaa (for example, arm/SVE: would be 
> an SVE related issue in the arm backend).  I'm certainly not against 
> having that.

Excellent.

> >>+<p>The brief summary encapsulates in a few words the intent of the
> >>+change.  For example: <code>cleanup check_field_decls</code>.</p>
> >
> >It should start with a capital though.  "Clean up blablal".  (So no
> >dot to end the sentence, this isn't a sentence).  A capital helps
> >the reader to quickly identify what is what, separate fluff from the
> >core parts.
> 
> There is a balance here to be made.  I'm mindful of Gerald's concern 
> that this is perhaps overly restrictive for new users already.  I 
> certainly think we should have a good house style, but getting too 
> prescriptive just gets in the way of attracting good contributions.

This is just basic email etiquette :-)

But, it's very annoying when you look at badly formatted subjects, in
"git log --oneline" for example, it is very obvious there (and long
subjects are problematic there as well btw).

Wrt balance: yes, that is one reason why I do not think we should
require all the markup stuff.

> >>+<p>Some large patch sets benefit from an introductory e-mail that
> >>+provides more context for the patch series and describes how the
> >>+patches have been broken up to provide for review.
> >
> >All non-trivial series, yeah.
> >
> >Maybe we should mention how v2 etc. of patch series should show what is
> >changed?  If there is a good standard practice for that at all :-)
> 
> Dunno.  I think that belongs primarily in the v2 0/n mail.  It's not, 
> after all, something that needs to be kept once the patches are applied.

Sure.  Ah, we could recommend that then, to make it clear in the vM 0/N
of some series which patches changed how.  My point is that it is a
waste of time to everyone if a reviewer has to drag through everything
every time; this is double true with git, it is easy to send updated
versions of patch sets often.


Segher

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

[Richard Earnshaw (lists)]

[-- Attachment #1: Type: text/plain, Size: 896 bytes --]


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

[-- Attachment #2: contrib.patch --]
[-- Type: text/x-patch, Size: 6900 bytes --]

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

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

[Richard Earnshaw (lists)]

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.

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

[Alexander Monakov]

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

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

[Richard Earnshaw (lists)]

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.

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

[Alexander Monakov]

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

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

[Jason Merrill]

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

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

[Richard Earnshaw (lists)]

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.

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

[Richard Earnshaw (lists)]

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.

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

[Segher Boessenkool]

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

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

[Richard Earnshaw (lists)]

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.

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

[Jonathan Wakely]

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.

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

[Richard Earnshaw (lists)]

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.

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

[Andrew Clayton]

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

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

[Segher Boessenkool]

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

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

[Segher Boessenkool]

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

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

[Michael Matz]

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.

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

[Richard Earnshaw (lists)]

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

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

[Michael Matz]

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.

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

[Jakub Jelinek]

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

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

[Michael Matz]

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.

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

[Andrew Stubbs]

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

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

[Segher Boessenkool]

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

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

[Richard Earnshaw (lists)]

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.

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

[Michael Matz]

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.

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

[Segher Boessenkool]

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

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

[Joseph Myers]

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

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

[Segher Boessenkool]

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

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

[Nathan Sidwell]

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

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

[Richard Earnshaw (lists)]

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.

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

[Segher Boessenkool]

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

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

[Nathan Sidwell]

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

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

[Jonathan Wakely]

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.

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

[Richard Earnshaw (lists)]

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.

Re: [wwwdocs] Updates to contribute.html for git-friendly posting rules

[Segher Boessenkool]

(Old thread, first time I see it though):

On Mon, Jan 20, 2020 at 11:45:28AM +0000, Richard Earnshaw (lists) wrote:
> The more we make the process lightweight for contributors, the more work 
> we make for maintainers.  If the contribution is sent correctly, then 
> ideally, the patch can be applied with just 'git am' by the maintainer. 

Almost always the maintainer will want to do "git am" followed by
"git commit --amend" *anyway*.  It helps if people follow the same
format often, but making this a stringent requirement, even before we
have experience with it, is just wrong, and does not help anyway.


Segher