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

[Jonathan Corbet <corbet@lwn.net>]

On Wed, 7 Nov 2018 21:51:38 +0100 (CET)
Thomas Gleixner <tglx@linutronix.de> wrote:

> 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.

Ah, but Dan said:

> 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. 

My concern is that you're going far beyond "local quirks" here, and
actually hiding the real quirks in the process. Just one example from
Ingo's email storm this (US/Mountain) morning:

> Even after a decade of introducing Git I still see Signed-off-by used as 
> an Acked-by or Reviewed-by substitutes, so I'd suggest adding this small 
> explanation as well:
> 
>   +   SOB chains should reflect the *real* route a patch took as it was 
>   +   propagated to us, with the first SOB entry signalling primary
>   +   authorship of a single author. Acks should be given as Acked-by 
>   +   lines and review approvals as Reviewed-by lines.

If SOB means anything like what it's supposed to mean, this *can't* be a
"local quirk" - we have to agree on it globally.

If you want to push this into the tree in something like its current form,
I'm not going to resist too hard - far be it from me to say we don't want
more documentation!  But allow me to complain a little.

Suppose I came along with my nifty new architecture, and it dragged in a
whole new set of timer and interrupt subsystems that duplicated a lot of
what's in the kernel now, but buried a few "local quirks" deep in the
middle.  "Don't worry", I say, "we'll factor out the common stuff later
once we figure out what it is; I'd rather not deal with the bikeshedding
now". Correct me if I'm wrong, but I suspect I might just get a response
back from you.  That's not how we normally do things.

This proposal takes a similar approach to the documentation.  Changelog
rules, your comment rules (other than tail comments), brace rules, line
breaks, etc. are common stuff; if they are not well-enough documented in
the global docs, the fix should really be applied there.  If it lands in
the current form, you know as well as I do that it will almost certainly
stay there for years, if not indefinitely.

IMO, the subsystem-specific documentation should be something that an
existing kernel developer can use to quickly learn how to avoid surprises
when wandering into a different subsystem.  So it should be concise and
strongly focused on the local customs.  If we don't start that way, I'm
afraid we'll never have that.  Then developers will miss the important
information, and we'll reinforce the image of the kernel project as a
collection of little fiefdoms that one wanders into at one's own risk.
And Documentation/ will continue to be a painful mess.

</soapbox>

Might it be worth asking Ted for a kernel summit slot to talk about this
next week?

(And thanks again for doing this!  I like the material and think we
definitely want it.)

jon