There is currently very little documentation in the kernel on maintainer
level tasks. In particular there are no documents on creating pull
requests to submit to Linus.
Quoting Greg Kroah-Hartman on LKML:
Anyway, this actually came up at the kernel summit / maintainer
meeting a few weeks ago, in that "how do I make a
good pull request to Linus" is something we need to document.
Here's what I do, and it seems to work well, so maybe we should turn
it into the start of the documentation for how to do it.
(quote references: kernel summit, Europe 2017)
Create a new kernel documentation book 'how to be a maintainer'
(suggested by Jonathan Corbet). Add chapters on 'configuring git' and
'creating a pull request'.
Most of the content was written by Linus Torvalds and Greg Kroah-Hartman
in discussion on LKML. This is stated at the start of one of the
chapters and the original email thread is referenced in
'pull-requests.rst'.
Signed-off-by: Tobin C. Harding <me@xxxxxxxx>
Reviewed-by: Greg Kroah-Hartman <gregkh@xxxxxxxxxxxxxxxxxxx>
---
v3:
- Modified details for branch and tag naming, suggested by Mauro
Carvalho Chehab.
- Added example email subject line for submitting pull requests.
- Re-added Greg's reviewed-by tag from version 1.
v2:
- Change title of book, suggested by Dan Williams.
---
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 | 182 +++++++++++++++++++++++++++++
5 files changed, 237 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
diff --git a/Documentation/index.rst b/Documentation/index.rst
index cb7f1ba5b3b1..a4fb34dddcf3 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -52,6 +52,7 @@ merged much easier.
dev-tools/index
doc-guide/index
kernel-hacking/index
+ maintainer/index
Kernel API documentation
------------------------
diff --git a/Documentation/maintainer/conf.py b/Documentation/maintainer/conf.py
new file mode 100644
index 000000000000..81e9eb7a7884
--- /dev/null
+++ b/Documentation/maintainer/conf.py
@@ -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'),
+]
diff --git a/Documentation/maintainer/configure-git.rst b/Documentation/maintainer/configure-git.rst
new file mode 100644
index 000000000000..78bbbb0d2c84
--- /dev/null
+++ b/Documentation/maintainer/configure-git.rst
@@ -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 = jd@xxxxxxxxxx
+ signingkey = jd@xxxxxxxxxx
+
+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)
diff --git a/Documentation/maintainer/index.rst b/Documentation/maintainer/index.rst
new file mode 100644
index 000000000000..fa84ac9cae39
--- /dev/null
+++ b/Documentation/maintainer/index.rst
@@ -0,0 +1,10 @@
+==========================
+Kernel Maintainer Handbook
+==========================
+
+.. toctree::
+ :maxdepth: 2
+
+ configure-git
+ pull-requests
+
diff --git a/Documentation/maintainer/pull-requests.rst b/Documentation/maintainer/pull-requests.rst
new file mode 100644
index 000000000000..a25e1002a5b9
--- /dev/null
+++ b/Documentation/maintainer/pull-requests.rst
@@ -0,0 +1,182 @@
+.. _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 <me@xxxxxxxx>.
+
+Original email thread::
+
+ http://lkml.kernel.org/r/20171114110500.GA21175@xxxxxxxxx
+
+
+Create Branch
+-------------
+
+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 a branch in the developers tree whom you intend to send the pull
+request to.
+
+In order to create the pull request you must first tag the branch that you
+have just created. It is recommended that you choose a meaningful tag name,
+in a way that you and others can understand, even after some time. A good
+practice is to include in the name an indicator of the sybsystem of origin
+and the target kernel version.
+
+So, by way of an example, Greg gives; a pull request with miscellaneous
+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
+
+that will create a signed tag called ``char-misc-4.15-rc1`` based on the
+last commit in the ``char-misc-next`` branch, and sign it with your gpg key
+(see :ref:`Documentation/maintainer/configure_git.rst <configuregit>`).
+
+Linus will only accept pull requests based on a signed tag. Other
+maintainers may differ.
+
+When you run the above command ``git`` will drop you into an editor and ask
+you to describe the tag. In this case, you are describing a pull request,
+so outline what is contained here, why it should be merged, and what, if
+any, testing has been done. All of this information will end up in the tag
+itself, and then in the merge commit that the maintainer makes if/when they
+merge the pull request. So write it up well, as it will be in the kernel
+tree for forever.
+
+As said by Linus::
+
+ Anyway, at least to me, the important part is the *message*. I want
+ to understand what I'm pulling, and why I should pull it. I also
+ want to use that message as the message for the merge, so it should
+ not just make sense to me, but make sense as a historical record
+ too.
+
+ Note that if there is something odd about the pull request, that
+ should very much be in the explanation. If you're touching files
+ that you don't maintain, explain _why_. I will see it in the
+ diffstat anyway, and if you didn't mention it, I'll just be extra
+ suspicious. And when you send me new stuff after the merge window
+ (or even bug-fixes, but ones that look scary), explain not just
+ what they do and why they do it, but explain the _timing_. What
+ happened that this didn't go through the merge window..
+
+ I will take both what you write in the email pull request _and_ in
+ the signed tag, so depending on your workflow, you can either
+ describe your work in the signed tag (which will also automatically
+ make it into the pull request email), or you can make the signed
+ tag just a placeholder with nothing interesting in it, and describe
+ the work later when you actually send me the pull request.
+
+ And yes, I will edit the message. Partly because I tend to do just
+ trivial formatting (the whole indentation and quoting etc), but
+ partly because part of the message may make sense for me at pull
+ time (describing the conflicts and your personal issues for sending
+ it right now), but may not make sense in the context of a merge
+ commit message, so I will try to make it all make sense. I will
+ also fix any speeling mistaeks and bad grammar I notice,
+ particularly for non-native speakers (but also for native ones
+ ;^). But I may miss some, or even add some.
+
+ Linus
+
+Greg gives, as an example pull request::
+
+ Char/Misc patches for 4.15-rc1
+
+ Here is the big char/misc patch set for the 4.15-rc1 merge window.
+ Contained in here is the normal set of new functions added to all
+ of these crazy drivers, as well as the following brand new
+ subsystems:
+ - time_travel_controller: Finally a set of drivers for the
+ latest time travel bus architecture that provides i/o to
+ the CPU before it asked for it, allowing uninterrupted
+ processing
+ - relativity_shifters: due to the affect that the
+ time_travel_controllers have on the overall system, there
+ was a need for a new set of relativity shifter drivers to
+ accommodate the newly formed black holes that would
+ threaten to suck CPUs into them. This subsystem handles
+ this in a way to successfully neutralize the problems.
+ There is a Kconfig option to force these to be enabled
+ when needed, so problems should not occur.
+
+ All of these patches have been successfully tested in the latest
+ linux-next releases, and the original problems that it found have
+ all been resolved (apologies to anyone living near Canberra for the
+ lack of the Kconfig options in the earlier versions of the
+ linux-next tree creations.)
+
+ Signed-off-by: Your-name-here <your_email@domain>
+
+
+The tag message format is just like a git commit id. One line at the top
+for a "summary subject" and be sure to sign-off at the bottom.
+
+Now that you have a local signed tag, you need to push it up to where it
+can be retrieved
+::
+
+ git push origin char-misc-4.15-rc1
+
+
+Create Pull Request
+-------------------
+
+The last thing to do is create the pull request message. ``git`` handily
+will do this for you with the ``git request-pull`` command, but it needs a
+bit of help determining what you want to pull, and on what to base the pull
+against (to show the correct changes to be pulled and the diffstat). The
+following command(s) will generate a pull request
+::
+
+ git request-pull master git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/char-misc.git/ char-misc-4.15-rc1
+
+Quoting Greg::
+
+ This is asking git to compare the difference from the
+ 'char-misc-4.15-rc1' tag location, to the head of the 'master'
+ branch (which in my case points to the last location in Linus's
+ tree that I diverged from, usually a -rc release) and to use the
+ git:// protocol to pull from. If you wish to use https://, that
+ can be used here instead as well (but note that some people behind
+ firewalls will have problems with https git pulls).
+
+ If the char-misc-4.15-rc1 tag is not present in the repo that I am
+ asking to be pulled from, git will complain saying it is not there,
+ a handy way to remember to actually push it to a public location.
+
+ The output of 'git request-pull' will contain the location of the
+ git tree and specific tag to pull from, and the full text
+ description of that tag (which is why you need to provide good
+ information in that tag). It will also create a diffstat of the
+ pull request, and a shortlog of the individual commits that the
+ pull request will provide.
+
+Linus responded that he tends to prefer the ``git://`` protocol. Other
+maintainers may have different preferences. Also, note that if you are
+creating pull requests without a signed tag then ``https://`` may be a
+better choice. Please see the original thread for the full discussion.
+
+
+Submit Pull Request
+-------------------
+
+A pull request is submitted in the same way as an ordinary patch. Send as
+inline email to the maintainer and CC LKML and any sub-system specific
+lists if required. Pull requests to Linus typically have a subject line
+something like
+::
+
+ [GIT PULL] <subsystem> changes for v4.15-rc1
--
2.7.4
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
