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

[Ingo Molnar <mingo@kernel.org>]

* Jonathan Corbet <corbet@lwn.net> wrote:

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

Yeah, I didn't intend this paragraph to be a local quirk - more like a 
reiteration of what the global rule already is (regardless of enforcement 
...), given the context.

I presume the cross section of readers of *both* the global documents and 
the -tip documents will be even smaller than just the readers of the -tip 
document - so some redundancy is beneficial. ;-)

In that sense the 'local' rules can also be indicators about which parts 
of the myriads of global rules the maintainers feel most strongly about, 
and are also a list of the most common problems we see in practice. Just 
repeating the very large set of global rules is counter-productive in 
that fashion. Maybe we should re-phrase and re-structure it into such a 
format, with references back to the original rules where we are just 
reiterating global rules? That would also allow the eventual inclusion of 
any clarification into the global rule.

Another aspect is that in -tip we are pretty strict about certain 
stylistic and not so stylistic details - this is partly a personal 
preference of the maintainers, and partly a maintainer workload reduction 
measure.

But level of enforcement matters and I think other trees can legitimately 
be more relaxed: when there's a lack of contributors then you *really* 
don't want to be the maintainer-from-hell who wants all i's dotted and 
all t's crossed, and you might not have the bandwidth to do it all 
yourself ...

Also I think there are and should be a lot of shades of grey when it 
comes to accepting patches, to find the right balance between pushing 
back on patches to improve quality and pulling in patches to move the 
kernel forward.

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

Yeah, so in -tip we don't do "local customs": we genuinely believe that 
*all* our rules where they go beyond the current development process 
would improve the generic kernel as well. (In fact if anyone can give 
reasons for why a particular rule is not an absolute advantage to the 
kernel we'd reconsider changing the rule.)

So your complaint is legitimate - how would you propose we handle this?

Thanks,

	Ingo