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

["Richard Earnshaw (lists)" <Richard dot Earnshaw at arm dot com>]

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