Skip to contentSkip to conversation

doc: add maintainer book

PATCH Superseded Tobin C. Harding 3 participants 8 messages Nov 24, 2017 – Nov 27, 2017

Subsystems (2)

v2 of 4 Superseded Latest is v4 →

lore
Share & tools
lore
#0 lore raw

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
index cb7f1ba5b3b1..a4fb34dddcf3 100644
@@ -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
new file mode 100644
index 000000000000..81e9eb7a7884
@@ -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
new file mode 100644
index 000000000000..78bbbb0d2c84
@@ -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
new file mode 100644
index 000000000000..fa84ac9cae39
@@ -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
#1 lore raw
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'.

---

You dropped my reviewed-by :(

#2 lore raw
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

---

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.

#3 lore raw
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'.

---

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

#4 lore raw
In reply to Tobin C. Harding

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

---

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
index cb7f1ba5b3b1..a4fb34dddcf3 100644
@@ -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
new file mode 100644
index 000000000000..81e9eb7a7884
@@ -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
new file mode 100644
index 000000000000..78bbbb0d2c84
@@ -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
new file mode 100644
index 000000000000..fa84ac9cae39
@@ -0,0 +1,10 @@
+==========================
+Kernel Maintainer Handbook
+==========================
+
+.. toctree::
+   :maxdepth: 2
+
+   configure-git
+   pull-requests
+
Documentation/maintainer/pull-requests.rst new file +21 -0
new file mode 100644
index 000000000000..0ca9f9bfd679
@@ -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

#5 lore raw
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'.

---

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
index cb7f1ba5b3b1..a4fb34dddcf3 100644
@@ -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
new file mode 100644
index 000000000000..81e9eb7a7884
@@ -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
new file mode 100644
index 000000000000..78bbbb0d2c84
@@ -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
new file mode 100644
index 000000000000..fa84ac9cae39
@@ -0,0 +1,10 @@
+==========================
+Kernel Maintainer Handbook
+==========================
+
+.. toctree::
+   :maxdepth: 2
+
+   configure-git
+   pull-requests
+
Documentation/maintainer/pull-requests.rst new file +21 -0
new file mode 100644
index 000000000000..0ca9f9bfd679
@@ -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.

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.

#6 lore raw

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

---

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
index cb7f1ba5b3b1..a4fb34dddcf3 100644
@@ -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
new file mode 100644
index 000000000000..81e9eb7a7884
@@ -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
new file mode 100644
index 000000000000..78bbbb0d2c84
@@ -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
new file mode 100644
index 000000000000..fa84ac9cae39
@@ -0,0 +1,10 @@
+==========================
+Kernel Maintainer Handbook
+==========================
+
+.. toctree::
+   :maxdepth: 2
+
+   configure-git
+   pull-requests
+
Documentation/maintainer/pull-requests.rst new file +21 -0
new file mode 100644
index 000000000000..0ca9f9bfd679
@@ -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).

Quoted 5 lines
Quoted 2 lines

Regards,
Mauro

Thanks 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

#7 lore raw
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'.

---

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
index cb7f1ba5b3b1..a4fb34dddcf3 100644
@@ -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
new file mode 100644
index 000000000000..81e9eb7a7884
@@ -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
new file mode 100644
index 000000000000..78bbbb0d2c84
@@ -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
new file mode 100644
index 000000000000..fa84ac9cae39
@@ -0,0 +1,10 @@
+==========================
+Kernel Maintainer Handbook
+==========================
+
+.. toctree::
+   :maxdepth: 2
+
+   configure-git
+   pull-requests
+
Documentation/maintainer/pull-requests.rst new file +21 -0
new file mode 100644
index 000000000000..0ca9f9bfd679
@@ -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).

Quoted 5 lines
Quoted 2 lines

Regards,
Mauro

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