Re: [PATCH v2] doc: add maintainer book

[Mauro Carvalho Chehab]

Em Sat, 25 Nov 2017 08:44:19 +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>
> ---
> 
> 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 = 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..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 <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 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