Re: git gcc-commit-mklog doesn't extract PR number to ChangeLog

[Jonathan Wakely <jwakely@redhat.com>]

On Thu, 10 Jun 2021 at 16:55, Tobias Burnus <tobias@codesourcery.com> wrote:
> Independent of the PR matching and checking issues, I think Jonathan was
> thinking about extending the documentation (as I gathered from IRC
> #gcc);

Right.

> I did not quite follow whether it is about best practice or
> contained bits which should be enforced.

My complaints about the current docs:

We do not say you should have a one-line subject in your git commit.
All we say at https://gcc.gnu.org/codingconventions.html#ChangeLogs is
that you should have "a leading text with git commit description".
This is vague. We should follow best practices, e.g.
https://chris.beams.io/posts/git-commit/ and **require** a one-line
summary, followed by a blank line, followed by the rest of the commit
msg (including the ChangeLog entries).

We do describe a preferred format for a one-line subject, but only
when documenting the format of emails to gcc-patches, at
https://gcc.gnu.org/contribute.html#patches
This is silly, we should not be recommending different formats for git
commits and patch emails, we should have one format which works for
both (which is what many people are already doing anyway). We should
document that format properly, in the coding conventions, and then the
email guidelines are much simpler because people have already written
good commit messages with one-line subjects.

So I want to improve the docs to describe best practices. If everybody
agrees with those best practices, we could start to enforce them.