linux-kernel - Re: [RFC] doc: add maintainer book

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: <CAPcyv4i6EhFAhxWDcoiw63XxvoTue2_Ov+Ooc9Nr1m2BS1qSVg@mail.gmail.com>
Date:   Fri, 24 Nov 2017 11:02:49 -0800
From:   Dan Williams <dan.j.williams@...el.com>
To:     "Tobin C. Harding" <me@...in.cc>
Cc:     Jonathan Corbet <corbet@....net>, linux-doc@...r.kernel.org,
        "linux-kernel@...r.kernel.org" <linux-kernel@...r.kernel.org>,
        Linus Torvalds <torvalds@...ux-foundation.org>,
        Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
        Ulf Hansson <ulf.hansson@...aro.org>,
        Jani Nikula <jani.nikula@...ux.intel.com>
Subject: Re: [RFC] doc: add maintainer book

On Tue, Nov 21, 2017 at 2:39 PM, Tobin C. Harding <me@...in.cc> wrote:
> There is currently very little documentation in the kernel on maintainer
> level tasks. In particular there are no documents on creating pull
> requests to submit to Linus.
>
> Quoting Greg Kroah-Hartman on LKML:
>
>     Anyway, this actually came up at the kernel summit / maintainer
>     meeting a few weeks ago, in that "how do I make a
>     good pull request to Linus" is something we need to document.
>
>     Here's what I do, and it seems to work well, so maybe we should turn
>     it into the start of the documentation for how to do it.
>
> (quote references: kernel summit, Europe 2017)
>
> Create a new kernel documentation book 'how to be a maintainer'
> (suggested by Jonathan Corbet). Add chapters on 'configuring git' and
> 'creating a pull request'.
>
> Most of the content was written by Linus Torvalds and Greg Kroah-Hartman
> in discussion on LKML. This is stated at the start of one of the
> chapters and the original email thread is referenced in
> 'pull-requests.rst'.
>
> Signed-off-by: Tobin C. Harding <me@...in.cc>
> ---
>
> Linus and Greg are CC'd because they are quoted heavily in the document.
>
> Greg,
>
> This is my second attempt at this but still it reads as if I am saying things
> that actually you said. I feel this is in the spirit of your original message
> but I would still like you to okay it please. Any suggestions (from anyone) on a
> better way to word, or structure, the document most welcome.
>
> thanks.
>
>
> Dan,
>
> Is this in line with your ideas for the maintainer documentation you have
> planned? I am a total noob at writing docs, please don't be shy to say if there
> is a better way.

This is a good start that we can build on, I'll let others comment on
the mechanical doc building details I want to focus on the content.
The only change I would make at this point is to the index...

[..]
> diff --git a/Documentation/maintainer/index.rst b/Documentation/maintainer/index.rst
> new file mode 100644
> index 000000000000..23dd28ec8762
> --- /dev/null
> +++ b/Documentation/maintainer/index.rst
> @@ -0,0 +1,10 @@
> +=============================
> +How to Be a Kernel Maintainer
> +=============================

Let's call this the "Kernel Maintainer Handbook". Unlike
SubmittingPatches and CodingStyle, this won't be a list of rules and
mandates but instead some common principles and practical advice that
maintainers will find useful, especially new and casual maintainers.

> +
> +.. toctree::
> +   :maxdepth: 2
> +
> +   configure-git
> +   pull-requests
> +
> diff --git a/Documentation/maintainer/pull-requests.rst b/Documentation/maintainer/pull-requests.rst
> new file mode 100644
> index 000000000000..0ca9f9bfd679
> --- /dev/null
> +++ b/Documentation/maintainer/pull-requests.rst
> @@ -0,0 +1,178 @@
> +.. _pullrequests:
> +
> +Creating Pull Requests
> +======================

It strikes me that the very next chapter we need to precede this one
is how to age commits in -next and the art of avoiding rebasing.