Re: [PATCH, RFC] A development process document

["Randy.Dunlap" <rdunlap@xenotime.net>]

On Thu, 31 Jul 2008, Daniel Barkalow wrote:

> On Thu, 31 Jul 2008, Jonathan Corbet wrote:
> 
> > On Thu, 31 Jul 2008 00:23:05 -0600
> > Alex Chiang <achiang@hp.com> wrote:
> > 
> > > Overall, a great document, as expected from you. I've replied with
> > > "content" comments below.
> > 
> > I've applied most of them, thanks.
> >  
> > > But it occurs to me that sending "style" comments to the editor of
> > > LWN is something akin to, well, some combination of Prometheus,
> > > Icarus, ravenous vultures, rabid penguins, and telling Linus that
> > > his choice of $EDITOR sucks, which is to say, "unwise".
> > 
> > Naw, English always needs debugging too.
> >  
> > > You've got url reference for some quotes but not all. Would it be
> > > possible to track them all down? Sorry for asking for all the extra
> > > work, but I think the references are useful, especially if the
> > > motivated reader actually visits said reference and gets all sides of
> > > the story.
> > 
> > I'll see what I can do.  Some of the older ones are kind of hard to find. 
> >  
> > > > +Patches must be prepared against a specific version of the
> > > > kernel.  As a +general rule, a patch should be based on the current
> > > > mainline as found in +Linus's git tree.  It may become necessary to
> > > > make versions against -mm,
> > >    ^^^^^^^
> > > Hm, is this the new recommended style? Grammar school taught me that
> > > it should be "Linus'" but I've noticed a gradually changing but
> > > inconsistently applied new school style.
> > 
> > I actually researched that a while back.  The rule, as far as I can tell
> > (and to the extent that English has real rules) is that the trailing "s" is
> > elided only when making a possessive of a plural noun.  "Linus", being very
> > much a unique, singular entity, needs to be "Linus's" in the possessive
> > form.
> >  
> > > > +If you have a significant series of patches, it is customary to
> > > > send an +introductory description as part zero.  In general, the
> > > > second and
> > > 
> > > This directly conflicts with akpm's advice:
> > > 
> > > 	http://www.zipworld.com.au/~akpm/linux/patches/stuff/tpp.txt
> > > 
> > > Section 6(b).
> > 
> > Interesting; Andrew didn't mention that in his review.  I think the intro
> > postings can be very useful in understanding a patch series as a whole.
> > Maybe I'll put in something about how anything which should be in the
> > changelogs needs to go with the actual patches.
> 
> If you include a [0/N], it's a cover letter, not a changelog portion. It 
> can be a useful way of providing context to reviewers as to the intended 
> total effect. Each of the patches should make sense standalone, but it's 
> not always clear from the individual patches what the total benefit is, 
> and a 0/N that explains can be worthwhile (and you'd want to make that 
> announcement to the mailing list, but not get it into the history).

but.. but Andrew often has to take part(s) of #0/N and add them to the
changelog(s) to make the changelog(s) meaningful.  I.e., someone skimped
on what should have been in the changelog(s).

> For example, if you have a series of patches that remove use of an old API 
> from various places, each of those patches cleans up some piece of code, 
> and these changelogs would say so, but it wouldn't be accurate (especially 
> if 5/N gets dropped or reverted later) to say anywhere that you've removed 
> all in-kernel use of the API; it's useful to include a cover letter that 
> says so.
> 
> The same sort of text can be included in individual patches, after the 
> tags and before the patch text, by putting a line '---' ahead of it; git, 
> by default, puts a per-patch diffstat there, but you can add other stuff 
> that will be helpful to reviewers but not future developers, like "this 
> should fix Andrew's laptop".

Yes, that's a good place for such comments.

-- 
~Randy