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

From: Jonathan Corbet <corbet@lwn.net>
To: Thomas Gleixner <tglx@linutronix.de>
Cc: LKML <linux-kernel@vger.kernel.org>,
	x86@kernel.org, Peter Zijlstra <peterz@infradead.org>,
	Paul McKenney <paulmck@linux.vnet.ibm.com>,
	John Stultz <john.stultz@linaro.org>,
	Arnaldo Carvalho de Melo <acme@redhat.com>,
	Frederic Weisbecker <frederic@kernel.org>,
	Andy Lutomirski <luto@kernel.org>,
	Marc Zyngier <marc.zyngier@arm.com>,
	Daniel Lezcano <daniel.lezcano@linaro.org>,
	Dave Hansen <dave.hansen@linux.intel.com>,
	Ard Biesheuvel <ard.biesheuvel@linaro.org>,
	Will Deacon <will.deacon@arm.com>,
	Mark Brown <broonie@kernel.org>,
	Dan Williams <dan.j.williams@intel.com>
Subject: Re: [patch 0/2] Documentation/process: Add subsystem/tree handbook
Date: Wed, 7 Nov 2018 12:48:55 -0700	[thread overview]
Message-ID: <20181107124855.328133e7@lwn.net> (raw)
In-Reply-To: <20181107171010.421878737@linutronix.de>

On Wed, 07 Nov 2018 18:10:10 +0100
Thomas Gleixner <tglx@linutronix.de> wrote:

> Mark recently suggested in one of the ksummit discussions to add subsystem
> or tree specific maintainer handbooks to document subsystem/tree specific
> development process information.
> 
> The following series adds the general section and the tip tree specific
> handbook.

So this is an idea that has gone around for a while; developers often get
into trouble when wandering into an unfamiliar part of the kernel, so
documenting the quaint local customs might help.  Assuming people actually
read the documentation, of course.

What's here seems generally good, but I do have an overall worry that we
may want to consider:

  - How much do we want to support and document subsystem-specific quirks
    vs. promoting reasonable and consistent rules kernel-wide?

There is a *lot* of stuff in the new tip manual.  Much of it, regarding
coding style and the writing of changelogs, really seems like it should be
global; if we need better documentation of that stuff, I'd really rather
see that advice folded into the central documents.  Having two (or more)
extensive coding-style documents doesn't seem like it's going to help us.

The stuff that is truly specific to tip seems fairly minimal:

  - what goes into tip
  - the reverse fir tree thing
  - tail comments, or the distaste thereabouts
  - subject-line prefixes

Having a tip-specific document that contains only those (plus whatever
else I forgot to list) would, IMO, make it much more likely that readers
would actually notice (and follow) the stuff that's specific to tip.

See what I'm getting at here?  Am I totally out to lunch on this?

Thanks,

jon

P.S. There is the separate issue of whether having subsystem-specific
     coding-style rules is a good thing overall.  I think we should try to
     be one big kernel project rather than 100 small ones, but perhaps
     that's just me.