Re: [RFC] doc: add maintainer book

[Tobin C. Harding]

On Fri, Nov 24, 2017 at 11:02:49AM -0800, Dan Williams wrote:
> On Tue, Nov 21, 2017 at 2:39 PM, Tobin C. Harding <me@xxxxxxxx> 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@xxxxxxxx>
> > ---
> >
> > 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.

Sounds good to me, I'll re-spin it with that change.

> > +
> > +.. 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.

I'd like to read this!

thanks,
Tobin.