From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752252AbdK3Krz (ORCPT ); Thu, 30 Nov 2017 05:47:55 -0500 Received: from out4-smtp.messagingengine.com ([66.111.4.28]:47557 "EHLO out4-smtp.messagingengine.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1750984AbdK3Krv (ORCPT ); Thu, 30 Nov 2017 05:47:51 -0500 X-ME-Sender: Date: Thu, 30 Nov 2017 21:47:44 +1100 From: "Tobin C. Harding" To: Mauro Carvalho Chehab Cc: Jonathan Corbet , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Linus Torvalds , Greg Kroah-Hartman , Ulf Hansson , Jani Nikula , Dan Williams Subject: Re: [PATCH v3] doc: add maintainer book Message-ID: <20171130104744.GV6217@eros> References: <1512006907-27400-1-git-send-email-me@tobin.cc> <20171130070119.2b17087b@vento.lan> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20171130070119.2b17087b@vento.lan> X-Mailer: Mutt 1.5.24 (2015-08-30) User-Agent: Mutt/1.5.24 (2015-08-30) Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Thu, Nov 30, 2017 at 07:01:19AM -0200, Mauro Carvalho Chehab wrote: > Em Thu, 30 Nov 2017 12:55:07 +1100 > "Tobin C. Harding" escreveu: > > > 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 > > Reviewed-by: Greg Kroah-Hartman > > > > --- > > > > 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 > > +` 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@domain.org > > + signingkey = jd@domain.org > > + > > +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 . > > + > > +Original email thread:: > > + > > + http://lkml.kernel.org/r/20171114110500.GA21175@kroah.com > > + > > + > > +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 > > Nitpick: there's an extra ";" character above: > gives; -> gives Ha ha, I thought for ages how to word this bit. The irony of grammar corrections from a non-native speaker is not lost on me :) Perhaps: By way of an example Greg gives, a pull request with miscellaneous I'll take any nitpicks you have Mauro, striving for perfection here. Thanks. > > +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 `). > > + > > +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 > > + > > + > > +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 > > +:: > > There's no need to place :: on a new line. Just write it as: > > can be retrieved:: Got it > > + > > + 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] changes for v4.15-rc1 > > With the above: > > Reviewed-by: Mauro Carvalho Chehab Will re-spin, add your suggestions and your tag. thanks, Tobin.