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

[Thomas Gleixner]

Dan,

On Wed, 7 Nov 2018, Dan Williams wrote:
> On Wed, Nov 7, 2018 at 11:49 AM Jonathan Corbet <corbet@xxxxxxx> wrote:
> > 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.

That was the intention here. I know that there is quite some stuff in that
document which could/should go into common documentation, but I have no
idea how much of it can be agreed on and how much different other
subsystems are looking at this. It's a braindump of all the things which
nag me/us in the daily business of patch juggling.

Jon, I agree that we should aim for as much consistency as we can. Though
if you look e.g. at comment style to begin with, then there is already
quite some disagreement. Changelog styles are a similar thing. Even if it's
somehow documented in the general documentation, some maintainers care and
others do not. The tip tree - and I have to admit especially myself - cares
a lot. I truly hate it when I have to look at useless, misleading or
uncomprehensible changelogs written by that Gleixner dude 10+ years ago.

We surely can spend a lot of time in bike shedding discussions how the
generally agreed guidelines should look like. But that would still leave
the contributors standing in the rain for a long time.

So I agree with Dan, that we should collect as much documentation from
subsystems/maintainers and get it into the tree so we can:

   - give contributors immediate access to subsystem/maintainer specific
     quirks

   - extract common views and move them into the general guidelines

   - have a clear idea which kind of things need to be discussed and agreed
     on and what might be left in the susbsystem/maintainer specific
     interpretation/expectation realm.

Thanks,

	tglx