doc: add maintainer book
Subsystems (2)
RFC 1/1 doc: add maintainer book
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'.
---
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.
thanks,
Tobin.
Documentation/index.rst | 1 + Documentation/maintainer/conf.py | 10 ++ Documentation/maintainer/configure-git.rst | 34 ++++++ Documentation/maintainer/index.rst | 10 ++ Documentation/maintainer/pull-requests.rst | 178 +++++++++++++++++++++++++++++ 5 files changed, 233 insertions(+) create mode 100644 Documentation/maintainer/conf.py create mode 100644 Documentation/maintainer/configure-git.rst create mode 100644 Documentation/maintainer/index.rst create mode 100644 Documentation/maintainer/pull-requests.rst
Documentation/index.rst +1 -0
@@ -52,6 +52,7 @@ merged much easier. dev-tools/index doc-guide/index kernel-hacking/index + maintainer/index Kernel API documentation ------------------------
Documentation/maintainer/conf.py new file +10 -0
@@ -0,0 +1,10 @@ +# -*- coding: utf-8; mode: python -*- + +project = 'Linux Kernel Development Documentation' + +tags.add("subproject") + +latex_documents = [ + ('index', 'maintainer.tex', 'Linux Kernel Development Documentation', + 'The kernel development community', 'manual'), +]
Documentation/maintainer/configure-git.rst new file +34 -0
@@ -0,0 +1,34 @@ +.. _configuregit: + +Configure Git +============= + +This chapter describes maintainer level git configuration. + +Tagged branches used in :ref:`Documentation/maintainer/pull-requests.rst +<pullrequests>` should be signed with the developers public GPG key. Signed +tags can be created by passing the ``-u`` flag to ``git tag``. However, +since you would *usually* use the same key for the same project, you can +set it once with +:: + + git config user.signingkey "keyname" + +Alternatively, edit your ``.git/config`` or ``~/.gitconfig`` file by hand: +:: + + [user] + name = Jane Developer + email = [email protected] + signingkey = [email protected] + +You may need to tell ``git`` to use ``gpg2`` +:: + + [gpg] + program = /path/to/gpg2 + +You may also like to tell ``gpg`` which ``tty`` to use (add to your shell rc file) +:: + + export GPG_TTY=$(tty)
Documentation/maintainer/index.rst new file +10 -0
@@ -0,0 +1,10 @@ +============================= +How to Be a Kernel Maintainer +============================= + +.. toctree:: + :maxdepth: 2 + + configure-git + pull-requests +
Documentation/maintainer/pull-requests.rst new file +178 -0
178 lines not on this page · raw message
Signature · 1 line
2.7.4
Quoted 27 lines · Tobin C. Harding
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 <[email protected]>---
Quoted 8 lines
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.
This looks great to me, thanks for starting it out. It can be added to more later (like the 'how to set up git' section), but that is easier to add to an existing document rather than just starting with none.
Quoted 36 lines · Tobin C. Harding
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 <[email protected]>---
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.
Quoted 8 lines
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...
[..]
Documentation/maintainer/index.rst line 3
Quoted 9 lines
Documentation/maintainer/index.rst new file +3
-0@@ -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.
Quoted 13 lines
Documentation/maintainer/index.rst new file +7
-0+ +.. toctree:: + :maxdepth: 2 + + configure-git + pull-requests +Documentation/maintainer/pull-requests.rst new file +0
-0
Documentation/maintainer/pull-requests.rst line 4
Quoted 4 lines
Documentation/maintainer/pull-requests.rst new file +4
-0@@ -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.
Quoted 51 lines · Dan Williams
Quoted 36 lines · Tobin C. Harding
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 <[email protected]>---
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.
Quoted 8 lines
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...
[..]
Quoted 14 lines
Documentation/maintainer/index.rst line 3
Quoted 9 lines
Documentation/maintainer/index.rst new file +3
-0@@ -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.
Quoted 12 lines
Quoted 12 lines
Documentation/maintainer/index.rst new file +7
-0+ +.. toctree:: + :maxdepth: 2 + + configure-git + pull-requests +Documentation/maintainer/pull-requests.rst new file +0
-0
Quoted 8 lines
Documentation/maintainer/pull-requests.rst line 4
Quoted 5 lines
Documentation/maintainer/pull-requests.rst new file +4
-0@@ -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.