lkml.org 
[lkml]   [2018]   [Nov]   [8]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    /
    Date
    From
    SubjectRe: [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@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

    \
     
     \ /
      Last update: 2018-11-08 16:49    [W:5.075 / U:0.064 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site