Messages in this thread | | | From | Dan Williams <> | Date | Wed, 7 Nov 2018 11:58:00 -0800 | Subject | Re: [patch 0/2] Documentation/process: Add subsystem/tree handbook |
| |
On Wed, Nov 7, 2018 at 11:49 AM Jonathan Corbet <corbet@lwn.net> wrote: > > On Wed, 07 Nov 2018 18:10:10 +0100 > Thomas Gleixner <tglx@linutronix.de> 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.
| |