[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <alpine.DEB.2.21.1811081637550.1549@nanos.tec.linutronix.de>
Date: Thu, 8 Nov 2018 16:49:04 +0100 (CET)
From: Thomas Gleixner <tglx@...utronix.de>
To: Jonathan Corbet <corbet@....net>
cc: Dan Williams <dan.j.williams@...el.com>,
Linux Kernel Mailing List <linux-kernel@...r.kernel.org>,
X86 ML <x86@...nel.org>, Peter Zijlstra <peterz@...radead.org>,
Paul McKenney <paulmck@...ux.vnet.ibm.com>,
john.stultz@...aro.org, acme@...hat.com, frederic@...nel.org,
Andy Lutomirski <luto@...nel.org>,
Marc Zyngier <marc.zyngier@....com>, daniel.lezcano@...aro.org,
Dave Hansen <dave.hansen@...ux.intel.com>,
Ard Biesheuvel <ard.biesheuvel@...aro.org>,
Will Deacon <will.deacon@....com>,
Mark Brown <broonie@...nel.org>
Subject: Re: [patch 0/2] Documentation/process: Add subsystem/tree handbook
Jon,
On Thu, 8 Nov 2018, Jonathan Corbet wrote:
> On Wed, 7 Nov 2018 21:51:38 +0100 (CET)
> Thomas Gleixner <tglx@...utronix.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
Powered by blists - more mailing lists