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