On Wed, Jan 22, 2020 at 10:00:00AM +0000, Richard Earnshaw (lists) wrote: > On 21/01/2020 19:26, Segher Boessenkool wrote: > >On Tue, Jan 21, 2020 at 02:52:00PM +0000, Richard Earnshaw (lists) wrote: > >>+ <li>A brief summary</li> > > > >You could stress that this is the one thing that really matters. And > >it's not a summary, it's much too brief for that (at most ~50 chars), > >but yup it should be something that allows *a human* to identify what > >this is. > > > > Well, it should all matter, or why are we requiring it?
Yes. > I'm happy to insert 'very' in front of 'brief' and to say elsewhere that > the entire subject (less the leading [...] part, should rarely, if ever, > go beyond 80 characters. The usual recommendation is 50 chars. Which is just about right with most MUAs. > >Everything else is just convention. > > > >>+<p>A component tag is a short identifier that identifies the part of > >>+the compiler being modified. This highlights to the relevant > >>+maintainers that the patch may need their attention. Multiple > >>+components may be listed if necessary. Each component tag should be > >>+followed by a colon. > > > >Often people use aaa/bbb: if drilling down a bit that way helps keep the > >subject short (which is the *point* of all this: keep things better > >consumable for humans). > > The aaa: bbb: is really for when aaa and bbb are independent parts of > the compiler and potentially needs multiple reviewers. aaa/bbb is when > bbb is strictly a sub-component of aaa (for example, arm/SVE: would be > an SVE related issue in the arm backend). I'm certainly not against > having that. Excellent. > >>+<p>The brief summary encapsulates in a few words the intent of the > >>+change. For example: <code>cleanup check_field_decls</code>.</p> > > > >It should start with a capital though. "Clean up blablal". (So no > >dot to end the sentence, this isn't a sentence). A capital helps > >the reader to quickly identify what is what, separate fluff from the > >core parts. > > There is a balance here to be made. I'm mindful of Gerald's concern > that this is perhaps overly restrictive for new users already. I > certainly think we should have a good house style, but getting too > prescriptive just gets in the way of attracting good contributions. This is just basic email etiquette :-) But, it's very annoying when you look at badly formatted subjects, in "git log --oneline" for example, it is very obvious there (and long subjects are problematic there as well btw). Wrt balance: yes, that is one reason why I do not think we should require all the markup stuff. > >>+<p>Some large patch sets benefit from an introductory e-mail that > >>+provides more context for the patch series and describes how the > >>+patches have been broken up to provide for review. > > > >All non-trivial series, yeah. > > > >Maybe we should mention how v2 etc. of patch series should show what is > >changed? If there is a good standard practice for that at all :-) > > Dunno. I think that belongs primarily in the v2 0/n mail. It's not, > after all, something that needs to be kept once the patches are applied. Sure. Ah, we could recommend that then, to make it clear in the vM 0/N of some series which patches changed how. My point is that it is a waste of time to everyone if a reviewer has to drag through everything every time; this is double true with git, it is easy to send updated versions of patch sets often. Segher
