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. -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
