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

Thomas Gleixner
2018-11-08T15:49:14Z

Jon,

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