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" <me@xxxxxxxx> 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 <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
>
> 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 <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
> > +::
>
> 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] <subsystem> changes for v4.15-rc1
>
> With the above:
>
> Reviewed-by: Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>
Will re-spin, add your suggestions and your tag.
thanks,
Tobin.
--
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
