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