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

Segher Boessenkool segher@kernel.crashing.org
Tue Jun 15 12:00:53 GMT 2021

On Mon, Jun 14, 2021 at 05:25:56PM +0100, Jonathan Wakely via Gcc-patches wrote:
> We don't currently say document anything about commit format for the
> wwwdocs repo. Should the "wwwdocs" be a classifier (as in this email)
> or a component tag?

I use proper components for wwwdocs as well, and when I send the patch
to gcc-patches@ I replace the [PATCH] by [wwwdocs].  It shouls not end
up in the repository after all, but we do need it in the mail.

> +<h4 id="Subject">Subject line</h4>
> +
> +<p>The first line of the commit message contains a brief summary that
> +encapsulates the intent of the change.
> +For example: <code>cleanup check_field_decls</code>.
> +Although, very short, the summary should be distinct so that it will
> +not be confused with other patches.</p>
> +
> +Additionally, the subject should begin with a component tag, followed by
> +an optional series identifier. When related to one or more bugs,
> +it should end with the bug numbers.
> +
> +<p>Ideally, the entire subject line should not exceed 75 characters.</p>

This is very wrong, and the cause of all other imperfections in this
proposal: the ideal subject line length is only 50 chars, so that all
important info in it shows up in a mail reader, and in gitk, tig,
git log --oneline, whatnot.  This has been a settled debate since
forever and a day, don't try to redo it :-/

> +<h4 id="Component">Component tags</h4>

If done properly you can put more info in a subject line by starting it
with the area the patch is about.  If done improperly you can blow the
50 chars length limit here already.

> +<h4>Series identifier</h4>
> +
> +<p>The series identifier is optional and is only relevant if a number of
> +patches are needed in order to effect an overall change.  It should be
> +a <i>short</i> string that identifies the series (it is common to all
> +commits in the series) and should be followed by a single dash surrounded
> +by white space.</p>

A "series identifier" does not belong in commits, only in the emails,
and you should use a tool (like git send-email) that handles this
automatically.  And the exact format is [PATCH m/n].  Sometimes people
add a "v2" or similar in there -- stuff in square brackets is deleted
when the patch is committed, so that is fine.  Most other decoorations
are useless, would only matter if you send more than a few 100+-patch
series daily (which I would recommend against for other reasons :-) )

> +<h4>Bug number</h4>
> +
> +<p>If your patch is related to a bug in the compiler for which there is an
> +existing PR number, the bug number should be stated.  Use the

The bug number *can* be stated.

> +short-form variant <code>[PR<i>nnnnn</i>]</code> without the bugzilla
> +component identifier and with no space between 'PR' and the number.
> +The body of the commit message should still contain the full form
> +(<code>PR <component>/<i>nnnnn</i></code>) so that Bugzilla
> +will correctly notice the commit.

Not the body anywhere, it should be in the changelog.

> +If your patch relates to two bugs, then write
> +<code>[PR<i>nnnnn</i>, PR<i>mmmmm</i>]</code>.

This is too long usually.

The most important thing is this should be at the *end* of the subject,
so that more important info is readable.  It can be nice if it is in the
subject of course, makes it a bit easier to search for, but it is mostly
irrelevant when scanning the commit log, or reading emails even.  I know
what bug PR323 is, but we have six-digit numbers now, you will recognise
only the few you spent most time with recently.

 - - -

IMNSHO this all should emphasise *why* these things are recommended, and
don't pretend these are "rules" at all.  They are not.  The important
thing is to make it easy for *others* to work with your patches.  Adding
frivolities does not help; concise, well-phrased, terse *does* help.


More information about the Gcc-patches mailing list