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