Re: [RFC] [wwwdocs] Rewrite docs on commit message and patch format

[Jonathan Wakely <jwakely@redhat.com>]

On Tue, 15 Jun 2021 at 01:12, Martin Sebor wrote:
>
> On 6/14/21 10:25 AM, Jonathan Wakely via Gcc-patches wrote:
> > I think this is an improvement on the current structure of the docs,
> > but I'd like to hear what others think.
>
> The text looks more detailed and arguably more accurate but also
> makes it sound more complicated and rigid than necessary.  It
> also doesn't look like the commit hook tries to enforce many of
> these elements.  If it did, quite a number of commits would fail.
>
> So I'm not sure about the value of documenting expectations that
> only few commits would meet.

We don't have to be too strict, but encouraging good practice still
makes the commit logs more useful. Even if only 50% of commit follow
it, that still seems to make the logs easier to skim than if there is
no consistency at all.

>  E.g., including the Component tag,
> or putting PRnnnnn at the end of the Subject line with no space
> (why ask for no space and not, for example PR #nnnnn?)  In fact,

That was always there, I just moved it from one page to another. I
have traditionally used a space before the bug number, so I'm fine
with that format, but I don't really think it makes the docs better to
list too many variations. And I am not trying to make big changes to
the policy with this patch, just reorganize the existing docs to
reflect the modern workflow (i.e. Git commits with automatically
generated ChangeLog files, rather than everything being about the
ChangeLog).

> unless we mean it (and are willing to enforce it) I think it
> would be best to either leave it out completely, or make it clear
> that it's not required.

If we don't enforce it, then it's not required. Commits that don't do
it will still get in.

I think suggesting a single format (but allowing variations on it) is
**much** better than not saying anything at all. For new contributors
it's helpful to say "this is what we want" so they have a guideline to
follow.

My revised patch sent a few minutes ago adds:

<p>A major benefit of a good, descriptive subject line is that it makes
the output of <code>git log --oneline</code> more useful. Including the
component tag and bug number(s) helps with that, but isn't compulsory
if the subject is already clear and has enough context.</p>

Does that make you happier?