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]

Date:   Wed, 7 Nov 2018 11:58:00 -0800
From:   Dan Williams <dan.j.williams@...el.com>
To:     Jonathan Corbet <corbet@....net>
Cc:     Thomas Gleixner <tglx@...utronix.de>,
        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

On Wed, Nov 7, 2018 at 11:49 AM Jonathan Corbet <corbet@....net> wrote:
>
> 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?

Not at all, and this is one of the thrusts of my talk next week at
Plumbers. I *do* want to propose that sub-systems document all their
local quirks. Then we can refactor the common ones into a global
document, have some discussion fodder if some sub-system specific
rules can be unified, and otherwise leave the freedom for individual
sub-systems to be different as long as it's documented.