doc: add maintainer book
Subsystems (2)
PATCH v2 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'.
---
v2:
- Change title of book, suggested by Dan Williams.
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 @@ +========================== +Kernel Maintainer Handbook +========================== + +.. 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 19 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'.
Quoted 7 lines
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]>---
You dropped my reviewed-by :(
Quoted 25 lines · Greg Kroah-Hartman
Quoted 24 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'.
Quoted 4 lines
Quoted 2 lines
Signed-off-by Tobin C. Harding <[email protected]>---
You dropped my reviewed-by :(
Oh, I didn't realize I was able to keep it between versions. I realize this was a reasonably trivial change but in general how much change is ok while keeping the reviewed-by? Who's call is it, the original author, the reviewed-by dev or the maintainer?
So v3 with your reviewed-by in the commit log below the signed-off tag. (ain't nothin like noise ;)
thanks,
Tobin.
Quoted 29 lines · Tobin C. Harding
Quoted 28 lines · Greg Kroah-Hartman
Quoted 26 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 6 lines
Quoted 1 line
You dropped my reviewed-by :(
Oh, I didn't realize I was able to keep it between versions. I realize this was a reasonably trivial change but in general how much change is ok while keeping the reviewed-by? Who's call is it, the original author, the reviewed-by dev or the maintainer?
Use your judgement, usually for tiny changes it's good to keep it so people don't have to keep reviewing it and adding it again.
thanks,
greg k-h
Em Sat, 25 Nov 2017 08:44:19 +1100
"Tobin C. Harding" <[email protected]> escreveu:
Quoted 155 lines
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]>---
v2:
- Change title of book, suggested by Dan Williams.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.rstDocumentation/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 @@ +========================== +Kernel Maintainer Handbook +========================== + +.. toctree:: + :maxdepth: 2 + + configure-git + pull-requests +Documentation/maintainer/pull-requests.rst new file +21
-0@@ -0,0 +1,178 @@ +.. _pullrequests: + +Creating Pull Requests +====================== + +This chapter describes how maintainers can create and submit pull requests +to other maintainers. This is useful for transferring changes from one +maintainers tree to another maintainers tree. + +This document was written by Tobin C. Harding (who at that time, was not an +experienced maintainer) primarily from comments made by Greg Kroah-Hartman +and Linus Torvalds on LKML. Suggestions and fixes by Jonathan Corbet. +Misrepresentation was unintentional but inevitable, please direct abuse to +Tobin C. Harding <[email protected]>. + +Original email thread:: + + http://lkml.kernel.org/r/[email protected] + + +Create Branch
Documentation/maintainer/pull-requests.rst line 31
Quoted 10 lines
Documentation/maintainer/pull-requests.rst new file +10
-0+------------- + +To start with you will need to have all the changes you wish to include in +the pull request on a separate branch. Typically you will base this branch +off of the developers tree whom you intend to send the pull request to. + +Name your branch in a semi-useful manner, some developers like to use +``for-linus`` for patches that are going to Linus. Greg uses +``char-misc-next`` for his ``char/misc`` driver patches to be merged into +``linux-next``.
The name of the branch doesn't really matter. At the Linux media tree, I just use "master" and "fixes" at the public maintainer's repository:
https://git.linuxtv.org/media_tree.git/
I don't care much on pushing branches from the tree at kernel.org, from where Linus pick my work:
https://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media.git/
I still push some branches there from time to time, but just because I was lazy enough to remove something from my scripts :-)
Also, Linus also uses "master" on his public tree ;-)
Locally, I actually use different names for my work branch (patchwork) and I have a "v4l_for_linus" branch from where I generate pull requests (with can either have a snapshot of "patchwork" or "fixes" branch, depending if the pull request is for a merge window or not). My internal names are mapped into the public ones via .git/config, like:
[remote "media_tree"] push = refs/heads/patchwork:refs/heads/master ...
In the past, I was using a different naming there, with the Kernel version on it, but somewhere in the past I opted to just use "master". The rationale is that people usually expect that the main development stuff to be on a "master" repository of a random git tree. Also, when I need, I create topic branches.
Anyway, the point is that the branch name actually depends on how each maintainer/each subsystem works.
So, I would remove the above paragraph, as I doubt there is a general rule for developer/maintainer's tree branches, and the name there doesn't matter much - except on subsystems that use topic branches.
Documentation/maintainer/pull-requests.rst line 42
Quoted 10 lines
Documentation/maintainer/pull-requests.rst new file +10
-0+In order to create the pull request you must first tag the branch that you +have just created. Name the tag with something useful that you can +understand if you run across it in a few weeks, and something that will be +"unique". Continuing Greg's example of the ``char-misc`` tree, for the +patches to be sent to Linus for the 4.15-rc1 merge window (as stated in the +above linked thread) he would name the tag 'char-misc-4.15-rc1'. +:: + + git tag -s char-misc-4.15-rc1 char-misc-next +
Now, the tag is what really matter, as this is what everybody sees on merges, on every clone of upstream's tree.
In the past, most maintainers were using something like for-linus or for_linus.
IMHO, not mentioning the subsystem's origin at the tag's name is a bad practice, as it makes harder to identify what tree was merged, specially during the merge window, where a lot merges happen on the first days. If you take a look at the recent logs, most maintainers add the name of the subsystem at their pull request branch/tag nowadays:
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/log/?qt=grep&q=merge+branch
(still, you would see some using tags/branches named "for_linus", "fixes" , etc)
So, I would change it to something like that:
"In order to create the pull request you must first tag the branch that you
have just created. It is recommended to choose a meaningful tag name, in a way that you and others can understand, even after some time. A good practice is to always include a name that will remind the subsystem of origin and the Kernel version the pull request's aiming. So, for example, a pull request with miscelaneous stuff for drivers/char, to be applied at the Kernel version 4.15-rc1 could be named as:
``char-misc-4.15-rc1``.
If such tag would be produced from a branch named ``char-misc-next``, you would be using the following command::
git tag -s char-misc-4.15-rc1 char-misc-next"
-
On a side note, in the case of media, I opt to name the tags with a sequencial number that it is unrelated to the rc version:
https://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media.git/refs/tags
Internally, I use a script that checks the last tag, and increments 1, if the upstream Kernel version is the same as the one at the last tag.
The reason is that it I don't submit pull requests for every single -rc kernel, and, sometimes, I end by submitting more than one pull request for a single -rc version (usually for -rc1).
Regards,
Mauro
Quoted 258 lines · Mauro Carvalho Chehab
Em Sat, 25 Nov 2017 08:44:19 +1100
"Tobin C. Harding" <[email protected]> escreveu:Quoted 155 lines
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]>---
v2:
- Change title of book, suggested by Dan Williams.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.rstDocumentation/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 @@ +========================== +Kernel Maintainer Handbook +========================== + +.. toctree:: + :maxdepth: 2 + + configure-git + pull-requests +Documentation/maintainer/pull-requests.rst new file +21
-0@@ -0,0 +1,178 @@ +.. _pullrequests: + +Creating Pull Requests +====================== + +This chapter describes how maintainers can create and submit pull requests +to other maintainers. This is useful for transferring changes from one +maintainers tree to another maintainers tree. + +This document was written by Tobin C. Harding (who at that time, was not an +experienced maintainer) primarily from comments made by Greg Kroah-Hartman +and Linus Torvalds on LKML. Suggestions and fixes by Jonathan Corbet. +Misrepresentation was unintentional but inevitable, please direct abuse to +Tobin C. Harding <[email protected]>. + +Original email thread:: + + http://lkml.kernel.org/r/[email protected] + + +Create BranchDocumentation/maintainer/pull-requests.rst line 31
Quoted 10 lines
Documentation/maintainer/pull-requests.rst new file +10
-0+------------- + +To start with you will need to have all the changes you wish to include in +the pull request on a separate branch. Typically you will base this branch +off of the developers tree whom you intend to send the pull request to. + +Name your branch in a semi-useful manner, some developers like to use +``for-linus`` for patches that are going to Linus. Greg uses +``char-misc-next`` for his ``char/misc`` driver patches to be merged into +``linux-next``.The name of the branch doesn't really matter. At the Linux media tree, I just use "master" and "fixes" at the public maintainer's repository:
https://git.linuxtv.org/media_tree.git/I don't care much on pushing branches from the tree at kernel.org, from where Linus pick my work:
https://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media.git/I still push some branches there from time to time, but just because I was lazy enough to remove something from my scripts :-)
Also, Linus also uses "master" on his public tree ;-)
Locally, I actually use different names for my work branch (patchwork) and I have a "
v4l_for_linus" branch from where I generate pull requests (with can either have a snapshot of "patchwork" or "fixes" branch, depending if the pull request is for a merge window or not). My internal names are mapped into the public ones via .git/config, like:[remote "media_tree"] push = refs/heads/patchwork:refs/heads/master ...In the past, I was using a different naming there, with the Kernel version on it, but somewhere in the past I opted to just use "master". The rationale is that people usually expect that the main development stuff to be on a "master" repository of a random git tree. Also, when I need, I create topic branches.
Anyway, the point is that the branch name actually depends on how each maintainer/each subsystem works.
So, I would remove the above paragraph, as I doubt there is a general rule for developer/maintainer's tree branches, and the name there doesn't matter much - except on subsystems that use topic branches.
Documentation/maintainer/pull-requests.rst line 42
Quoted 10 lines
Documentation/maintainer/pull-requests.rst new file +10
-0+In order to create the pull request you must first tag the branch that you +have just created. Name the tag with something useful that you can +understand if you run across it in a few weeks, and something that will be +"unique". Continuing Greg's example of the ``char-misc`` tree, for the +patches to be sent to Linus for the 4.15-rc1 merge window (as stated in the +above linked thread) he would name the tag 'char-misc-4.15-rc1'. +:: + + git tag -s char-misc-4.15-rc1 char-misc-next +Now, the tag is what really matter, as this is what everybody sees on merges, on every clone of upstream's tree.
In the past, most maintainers were using something like for-linus or
for_linus.IMHO, not mentioning the subsystem's origin at the tag's name is a bad practice, as it makes harder to identify what tree was merged, specially during the merge window, where a lot merges happen on the first days. If you take a look at the recent logs, most maintainers add the name of the subsystem at their pull request branch/tag nowadays:
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/log/?qt=grep&q=merge+branch
(still, you would see some using tags/branches named "
for_linus", "fixes" , etc)So, I would change it to something like that:
"In order to create the pull request you must first tag the branch that you
have just created. It is recommended to choose a meaningful tag name, in a way that you and others can understand, even after some time. A good practice is to always include a name that will remind the subsystem of origin and the Kernel version the pull request's aiming. So, for example, a pull request with miscelaneous stuff fordrivers/char, to be applied at the Kernel version 4.15-rc1 could be named as:
``char-misc-4.15-rc1``.If such tag would be produced from a branch named ``char-misc-next``, you would be using the following command::
git tag -s char-misc-4.15-rc1 char-misc-next"-
On a side note, in the case of media, I opt to name the tags with a sequencial number that it is unrelated to the rc version:
https://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media.git/refs/tags
Internally, I use a script that checks the last tag, and increments 1, if the upstream Kernel version is the same as the one at the last tag.
Quoted 6 lines
The reason is that it I don't submit pull requests for every single -rc kernel, and, sometimes, I end by submitting more than one pull request for a single -rc version (usually for -rc1).
Regards,
Mauro
Thanks for your suggestions Mauro. Unless any other comments come in on this I'll work your changes into the next version.
Is there a _correct_ spelling of 'kernel'? Should it be capitalized or not? You use 'Kernel' but the rest of the document uses 'kernel', I think we should have a single spelling (at least inside a single document).
thanks,
Tobin.
Em Tue, 28 Nov 2017 07:53:03 +1100
"Tobin C. Harding" <[email protected]> escreveu:
Quoted 263 lines · Mauro Carvalho Chehab
Quoted 262 lines
Em Sat, 25 Nov 2017 08:44:19 +1100
"Tobin C. Harding" <[email protected]> escreveu:Quoted 155 lines
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]>---
v2:
- Change title of book, suggested by Dan Williams.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.rstDocumentation/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 @@ +========================== +Kernel Maintainer Handbook +========================== + +.. toctree:: + :maxdepth: 2 + + configure-git + pull-requests +Documentation/maintainer/pull-requests.rst new file +21
-0@@ -0,0 +1,178 @@ +.. _pullrequests: + +Creating Pull Requests +====================== + +This chapter describes how maintainers can create and submit pull requests +to other maintainers. This is useful for transferring changes from one +maintainers tree to another maintainers tree. + +This document was written by Tobin C. Harding (who at that time, was not an +experienced maintainer) primarily from comments made by Greg Kroah-Hartman +and Linus Torvalds on LKML. Suggestions and fixes by Jonathan Corbet. +Misrepresentation was unintentional but inevitable, please direct abuse to +Tobin C. Harding <[email protected]>. + +Original email thread:: + + http://lkml.kernel.org/r/[email protected] + + +Create BranchDocumentation/maintainer/pull-requests.rst line 31
Quoted 10 lines
Documentation/maintainer/pull-requests.rst new file +10
-0+------------- + +To start with you will need to have all the changes you wish to include in +the pull request on a separate branch. Typically you will base this branch +off of the developers tree whom you intend to send the pull request to. + +Name your branch in a semi-useful manner, some developers like to use +``for-linus`` for patches that are going to Linus. Greg uses +``char-misc-next`` for his ``char/misc`` driver patches to be merged into +``linux-next``.The name of the branch doesn't really matter. At the Linux media tree, I just use "master" and "fixes" at the public maintainer's repository:
https://git.linuxtv.org/media_tree.git/I don't care much on pushing branches from the tree at kernel.org, from where Linus pick my work:
https://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media.git/I still push some branches there from time to time, but just because I was lazy enough to remove something from my scripts :-)
Also, Linus also uses "master" on his public tree ;-)
Locally, I actually use different names for my work branch (patchwork) and I have a "
v4l_for_linus" branch from where I generate pull requests (with can either have a snapshot of "patchwork" or "fixes" branch, depending if the pull request is for a merge window or not). My internal names are mapped into the public ones via .git/config, like:[remote "media_tree"] push = refs/heads/patchwork:refs/heads/master ...In the past, I was using a different naming there, with the Kernel version on it, but somewhere in the past I opted to just use "master". The rationale is that people usually expect that the main development stuff to be on a "master" repository of a random git tree. Also, when I need, I create topic branches.
Anyway, the point is that the branch name actually depends on how each maintainer/each subsystem works.
So, I would remove the above paragraph, as I doubt there is a general rule for developer/maintainer's tree branches, and the name there doesn't matter much - except on subsystems that use topic branches.
Documentation/maintainer/pull-requests.rst line 42
Quoted 10 lines
Documentation/maintainer/pull-requests.rst new file +10
-0+In order to create the pull request you must first tag the branch that you +have just created. Name the tag with something useful that you can +understand if you run across it in a few weeks, and something that will be +"unique". Continuing Greg's example of the ``char-misc`` tree, for the +patches to be sent to Linus for the 4.15-rc1 merge window (as stated in the +above linked thread) he would name the tag 'char-misc-4.15-rc1'. +:: + + git tag -s char-misc-4.15-rc1 char-misc-next +Now, the tag is what really matter, as this is what everybody sees on merges, on every clone of upstream's tree.
In the past, most maintainers were using something like for-linus or
for_linus.IMHO, not mentioning the subsystem's origin at the tag's name is a bad practice, as it makes harder to identify what tree was merged, specially during the merge window, where a lot merges happen on the first days. If you take a look at the recent logs, most maintainers add the name of the subsystem at their pull request branch/tag nowadays:
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/log/?qt=grep&q=merge+branch
(still, you would see some using tags/branches named "
for_linus", "fixes" , etc)So, I would change it to something like that:
"In order to create the pull request you must first tag the branch that you
have just created. It is recommended to choose a meaningful tag name, in a way that you and others can understand, even after some time. A good practice is to always include a name that will remind the subsystem of origin and the Kernel version the pull request's aiming. So, for example, a pull request with miscelaneous stuff fordrivers/char, to be applied at the Kernel version 4.15-rc1 could be named as:
``char-misc-4.15-rc1``.If such tag would be produced from a branch named ``char-misc-next``, you would be using the following command::
git tag -s char-misc-4.15-rc1 char-misc-next"-
On a side note, in the case of media, I opt to name the tags with a sequencial number that it is unrelated to the rc version:
https://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media.git/refs/tags
Internally, I use a script that checks the last tag, and increments 1, if the upstream Kernel version is the same as the one at the last tag.
The reason is that it I don't submit pull requests for every single -rc kernel, and, sometimes, I end by submitting more than one pull request for a single -rc version (usually for -rc1).
Quoted 5 lines
Quoted 2 lines
Regards,
MauroThanks for your suggestions Mauro. Unless any other comments come in on this I'll work your changes into the next version.
Ok.
Quoted 4 lines
Is there a _correct_ spelling of 'kernel'? Should it be capitalized or not? You use 'Kernel' but the rest of the document uses 'kernel', I think we should have a single spelling (at least inside a single document).
I always use Kernel when referring to The Linux Kernel, as I'm not talking about any other kernel, but about a particular one. For me, "Kernel" is a shortcut for its full name (as "Linux" would be another shortcut - but I prefer Kernel, because it leads no doubts that I'm talking about only its core). IMO, that is the proper way to refer to it, in English.
Yet, I saw others that don't capitalize it.
Regards,
Mauro
Quoted 274 lines · Mauro Carvalho Chehab
Em Tue, 28 Nov 2017 07:53:03 +1100
"Tobin C. Harding" <[email protected]> escreveu:Quoted 263 lines · Mauro Carvalho Chehab
Quoted 262 lines
Em Sat, 25 Nov 2017 08:44:19 +1100
"Tobin C. Harding" <[email protected]> escreveu:Quoted 155 lines
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]>---
v2:
- Change title of book, suggested by Dan Williams.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.rstDocumentation/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 @@ +========================== +Kernel Maintainer Handbook +========================== + +.. toctree:: + :maxdepth: 2 + + configure-git + pull-requests +Documentation/maintainer/pull-requests.rst new file +21
-0@@ -0,0 +1,178 @@ +.. _pullrequests: + +Creating Pull Requests +====================== + +This chapter describes how maintainers can create and submit pull requests +to other maintainers. This is useful for transferring changes from one +maintainers tree to another maintainers tree. + +This document was written by Tobin C. Harding (who at that time, was not an +experienced maintainer) primarily from comments made by Greg Kroah-Hartman +and Linus Torvalds on LKML. Suggestions and fixes by Jonathan Corbet. +Misrepresentation was unintentional but inevitable, please direct abuse to +Tobin C. Harding <[email protected]>. + +Original email thread:: + + http://lkml.kernel.org/r/[email protected] + + +Create BranchDocumentation/maintainer/pull-requests.rst line 31
Quoted 10 lines
Documentation/maintainer/pull-requests.rst new file +10
-0+------------- + +To start with you will need to have all the changes you wish to include in +the pull request on a separate branch. Typically you will base this branch +off of the developers tree whom you intend to send the pull request to. + +Name your branch in a semi-useful manner, some developers like to use +``for-linus`` for patches that are going to Linus. Greg uses +``char-misc-next`` for his ``char/misc`` driver patches to be merged into +``linux-next``.The name of the branch doesn't really matter. At the Linux media tree, I just use "master" and "fixes" at the public maintainer's repository:
https://git.linuxtv.org/media_tree.git/I don't care much on pushing branches from the tree at kernel.org, from where Linus pick my work:
https://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media.git/I still push some branches there from time to time, but just because I was lazy enough to remove something from my scripts :-)
Also, Linus also uses "master" on his public tree ;-)
Locally, I actually use different names for my work branch (patchwork) and I have a "
v4l_for_linus" branch from where I generate pull requests (with can either have a snapshot of "patchwork" or "fixes" branch, depending if the pull request is for a merge window or not). My internal names are mapped into the public ones via .git/config, like:[remote "media_tree"] push = refs/heads/patchwork:refs/heads/master ...In the past, I was using a different naming there, with the Kernel version on it, but somewhere in the past I opted to just use "master". The rationale is that people usually expect that the main development stuff to be on a "master" repository of a random git tree. Also, when I need, I create topic branches.
Anyway, the point is that the branch name actually depends on how each maintainer/each subsystem works.
So, I would remove the above paragraph, as I doubt there is a general rule for developer/maintainer's tree branches, and the name there doesn't matter much - except on subsystems that use topic branches.
Documentation/maintainer/pull-requests.rst line 42
Quoted 10 lines
Documentation/maintainer/pull-requests.rst new file +10
-0+In order to create the pull request you must first tag the branch that you +have just created. Name the tag with something useful that you can +understand if you run across it in a few weeks, and something that will be +"unique". Continuing Greg's example of the ``char-misc`` tree, for the +patches to be sent to Linus for the 4.15-rc1 merge window (as stated in the +above linked thread) he would name the tag 'char-misc-4.15-rc1'. +:: + + git tag -s char-misc-4.15-rc1 char-misc-next +Now, the tag is what really matter, as this is what everybody sees on merges, on every clone of upstream's tree.
In the past, most maintainers were using something like for-linus or
for_linus.IMHO, not mentioning the subsystem's origin at the tag's name is a bad practice, as it makes harder to identify what tree was merged, specially during the merge window, where a lot merges happen on the first days. If you take a look at the recent logs, most maintainers add the name of the subsystem at their pull request branch/tag nowadays:
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/log/?qt=grep&q=merge+branch
(still, you would see some using tags/branches named "
for_linus", "fixes" , etc)So, I would change it to something like that:
"In order to create the pull request you must first tag the branch that you
have just created. It is recommended to choose a meaningful tag name, in a way that you and others can understand, even after some time. A good practice is to always include a name that will remind the subsystem of origin and the Kernel version the pull request's aiming. So, for example, a pull request with miscelaneous stuff fordrivers/char, to be applied at the Kernel version 4.15-rc1 could be named as:
``char-misc-4.15-rc1``.If such tag would be produced from a branch named ``char-misc-next``, you would be using the following command::
git tag -s char-misc-4.15-rc1 char-misc-next"-
On a side note, in the case of media, I opt to name the tags with a sequencial number that it is unrelated to the rc version:
https://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media.git/refs/tags
Internally, I use a script that checks the last tag, and increments 1, if the upstream Kernel version is the same as the one at the last tag.
The reason is that it I don't submit pull requests for every single -rc kernel, and, sometimes, I end by submitting more than one pull request for a single -rc version (usually for -rc1).
Quoted 5 lines
Quoted 2 lines
Regards,
MauroThanks for your suggestions Mauro. Unless any other comments come in on this I'll work your changes into the next version.
Ok.
Quoted 7 lines
Quoted 4 lines
Is there a _correct_ spelling of 'kernel'? Should it be capitalized or not? You use 'Kernel' but the rest of the document uses 'kernel', I think we should have a single spelling (at least inside a single document).
I always use Kernel when referring to The Linux Kernel, as I'm not talking about any other kernel, but about a particular one.
This sounds grammatically correct.
Quoted 4 lines
For me, "Kernel" is a shortcut for its full name (as "Linux" would be another shortcut - but I prefer Kernel, because it leads no doubts that I'm talking about only its core). IMO, that is the proper way to refer to it, in English.
This seems like a valid argument to me. I've seen Linus refer to the kernel as 'Linux' and this leaves no ambiguity but it seems for any other speaker there can be some ambiguity.
I believe I will follow your lead and refer to the Linux Kernel as 'Kernel' from now on.
Quoted 1 line
Yet, I saw others that don't capitalize it.
Not every one is anal about language and grammar ;)
thanks,
Tobin.