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

[Thomas Gleixner]

Jon,

On Thu, 8 Nov 2018, Jonathan Corbet wrote:
> On Wed, 7 Nov 2018 21:51:38 +0100 (CET)
> Thomas Gleixner <tglx@xxxxxxxxxxxxx> wrote:
> >   +   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.

Agreed.

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

Please ask for allowance next time _before_ complaining :)

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

Darn. Not much I can argue about.

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

Fair enough. TBH, I picked up Marks idea and it started out small and then
all the stuff which itches me/us got dumped into it. Let me try to split
that into pieces.

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

Aside of the scheduling conflicts, definitely yes.

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

At least it was not complete waste of time then :)

Thanks,

	tglx