On Mon, Nov 27, 2017 at 07:01:23PM -0200, Mauro Carvalho Chehab wrote:
> Em Tue, 28 Nov 2017 07:53:03 +1100
> "Tobin C. Harding" <m...@tobin.cc> escreveu:
>
> > On Mon, Nov 27, 2017 at 04:57:30PM -0200, Mauro Carvalho Chehab wrote:
> > > Em Sat, 25 Nov 2017 08:44:19 +1100
> > > "Tobin C. Harding" <m...@tobin.cc> 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 <m...@tobin.cc>
> > > > ---
> > > >
> > > > 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
> > > >
> > > > 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 = j...@domain.org
> > > > + signingkey = j...@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..0ca9f9bfd679
> > > > --- /dev/null
> > > > +++ b/Documentation/maintainer/pull-requests.rst
> > > > @@ -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 <m...@tobin.cc>.
> > > > +
> > > > +Original email thread::
> > > > +
> > > > + http://lkml.kernel.org/r/20171114110500.ga21...@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 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.
> > >
> > > > +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
> >
> > Thanks for your suggestions Mauro. Unless any other comments come in on
> > this I'll work your changes into the next version.
>
> Ok.
>
> > 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.
> 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.
> Yet, I saw others that don't capitalize it.
Not every one is anal about language and grammar ;)
thanks,
Tobin.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
