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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20181107124855.328133e7@lwn.net>
Date:   Wed, 7 Nov 2018 12:48:55 -0700
From:   Jonathan Corbet <corbet@....net>
To:     Thomas Gleixner <tglx@...utronix.de>
Cc:     LKML <linux-kernel@...r.kernel.org>, x86@...nel.org,
        Peter Zijlstra <peterz@...radead.org>,
        Paul McKenney <paulmck@...ux.vnet.ibm.com>,
        John Stultz <john.stultz@...aro.org>,
        Arnaldo Carvalho de Melo <acme@...hat.com>,
        Frederic Weisbecker <frederic@...nel.org>,
        Andy Lutomirski <luto@...nel.org>,
        Marc Zyngier <marc.zyngier@....com>,
        Daniel Lezcano <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>,
        Dan Williams <dan.j.williams@...el.com>
Subject: Re: [patch 0/2] Documentation/process: Add subsystem/tree handbook

On Wed, 07 Nov 2018 18:10:10 +0100
Thomas Gleixner <tglx@...utronix.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.