On Thu, 10 Jun 2021 at 16:55, Tobias Burnus <tob...@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.
