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