Re: [patch 0/2] Documentation/process: Add subsystem/tree handbook

[Dan Williams]

On Wed, Nov 7, 2018 at 11:49 AM Jonathan Corbet <corbet@xxxxxxx> wrote:
>
> On Wed, 07 Nov 2018 18:10:10 +0100
> Thomas Gleixner <tglx@xxxxxxxxxxxxx> wrote:
>
> > Mark recently suggested in one of the ksummit discussions to add subsystem
> > or tree specific maintainer handbooks to document subsystem/tree specific
> > development process information.
> >
> > The following series adds the general section and the tip tree specific
> > handbook.
>
> So this is an idea that has gone around for a while; developers often get
> into trouble when wandering into an unfamiliar part of the kernel, so
> documenting the quaint local customs might help.  Assuming people actually
> read the documentation, of course.
>
> What's here seems generally good, but I do have an overall worry that we
> may want to consider:
>
>   - How much do we want to support and document subsystem-specific quirks
>     vs. promoting reasonable and consistent rules kernel-wide?
>
> There is a *lot* of stuff in the new tip manual.  Much of it, regarding
> coding style and the writing of changelogs, really seems like it should be
> global; if we need better documentation of that stuff, I'd really rather
> see that advice folded into the central documents.  Having two (or more)
> extensive coding-style documents doesn't seem like it's going to help us.
>
> The stuff that is truly specific to tip seems fairly minimal:
>
>   - what goes into tip
>   - the reverse fir tree thing
>   - tail comments, or the distaste thereabouts
>   - subject-line prefixes
>
> Having a tip-specific document that contains only those (plus whatever
> else I forgot to list) would, IMO, make it much more likely that readers
> would actually notice (and follow) the stuff that's specific to tip.
>
> See what I'm getting at here?  Am I totally out to lunch on this?

Not at all, and this is one of the thrusts of my talk next week at
Plumbers. I *do* want to propose that sub-systems document all their
local quirks. Then we can refactor the common ones into a global
document, have some discussion fodder if some sub-system specific
rules can be unified, and otherwise leave the freedom for individual
sub-systems to be different as long as it's documented.