On Tue, 15 Jun 2021 at 14:03, Segher Boessenkool wrote: > > 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 :-/
The existing docs say 75 chars: https://gcc.gnu.org/contribute.html#patches The frustrating thing about this proposal is that all I'm really trying to do is restructure the existing policies to be documented in more sensible places, and everybody is picking holes in the existing policy as though I'm introducing 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. I didn't invent this, it's the existing policy: https://gcc.gnu.org/contribute.html#patches The [PATCH v2] or [PATCH m/n] is part of the "classifier", which is separate from the "series identifier" you're objecting to. The m/n part is called a "series marker" within the "classifier". > > > +<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. Again, you're objecting to the current text: https://gcc.gnu.org/contribute.html#patches > > > +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. That's the current text: https://gcc.gnu.org/contribute.html#patches > > +If your patch relates to two bugs, then write > > +<code>[PR<i>nnnnn</i>, PR<i>mmmmm</i>]</code>. > > This is too long usually. That's the current text: https://gcc.gnu.org/contribute.html#patches > 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. If I was trying to improve the current policy, I would agree. I'm not. I'm just trying to move the existing text around, without significant changes to the content of that text. I'm all for improving the policies, but that's not what I'm trying to do here. I would like to move things to a more sensible place **first** and then we can improve them.
