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

Martin Sebor msebor@gmail.com
Tue Jun 15 17:37:37 GMT 2021

On 6/15/21 3:39 AM, Jonathan Wakely wrote:
> 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?

I expect most users to read this text either before they commit
their first GCC change or after the commit hook rejects it.  At
that point, what they'll want to find out as quickly and
effortlessly as possible, is what they need to do to get
the patch committed without an error.  Reading several paragraphs
of best practices isn't likely to be the most expedient way to
figure that out.  What it will be is frustrating, especially if
the hard requirements are sprinkled among but not obviously
distinguished from the best practices, and if following some
but not others doesn't resolve the error.

To minimize the frustration I'd suggest to identify the hard
requirements and add links showing examples of representative
commits that follow the best practices.  Then the rest of the text
can go over all the details of classifiers and component tags, etc.,
with more links to example commits.

As an aside, adopting the same conventions across all toolchain
projects (Binutils/GDB, GCC, and Glibc) would simplify things
for contributors to all of them.


PS To the point of pulling up git log and using the last commit
as a template: that works but unless the last commit follows
the best practices it doesn't accomplish what you want.

More information about the Gcc-patches mailing list