[PATCH v2] doc: add maintainer book

[PATCH v2] doc: add maintainer book

[Tobin C. Harding]

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@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 = 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..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@tobin.cc>.
+
+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 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``.
+
+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
+
+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
+email to the maintainer and CC LKML and any sub-system specific lists
+if required.
-- 
2.7.4

Re: [PATCH v2] doc: add maintainer book

[Greg Kroah-Hartman]

On Sat, Nov 25, 2017 at 08:44:19AM +1100, Tobin C. Harding wrote:
> 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@tobin.cc>
> ---

You dropped my reviewed-by :(

Re: [PATCH v2] doc: add maintainer book

[Tobin C. Harding]

On Sat, Nov 25, 2017 at 08:56:23AM +0100, Greg Kroah-Hartman wrote:
> On Sat, Nov 25, 2017 at 08:44:19AM +1100, Tobin C. Harding wrote:
> > 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@tobin.cc>
> > ---
> 
> You dropped my reviewed-by :(

Oh, I didn't realize I was able to keep it between versions. I realize
this was a reasonably trivial change but in general how much change is
ok while keeping the reviewed-by? Who's call is it, the original
author, the reviewed-by dev or the maintainer?

So v3 with your reviewed-by in the commit log below the signed-off
tag. (ain't nothin like noise ;)

thanks,
Tobin.

Re: [PATCH v2] doc: add maintainer book

[Greg Kroah-Hartman]

On Sat, Nov 25, 2017 at 07:22:36PM +1100, Tobin C. Harding wrote:
> On Sat, Nov 25, 2017 at 08:56:23AM +0100, Greg Kroah-Hartman wrote:
> > On Sat, Nov 25, 2017 at 08:44:19AM +1100, Tobin C. Harding wrote:
> > > 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@tobin.cc>
> > > ---
> > 
> > You dropped my reviewed-by :(
> 
> Oh, I didn't realize I was able to keep it between versions. I realize
> this was a reasonably trivial change but in general how much change is
> ok while keeping the reviewed-by? Who's call is it, the original
> author, the reviewed-by dev or the maintainer?

Use your judgement, usually for tiny changes it's good to keep it so
people don't have to keep reviewing it and adding it again.

thanks,

greg k-h

Re: [PATCH v2] doc: add maintainer book

[Mauro Carvalho Chehab]

Em Sat, 25 Nov 2017 08:44:19 +1100
"Tobin C. Harding" <me@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 <me@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 = 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..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@tobin.cc>.
> +
> +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 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

Re: [PATCH v2] doc: add maintainer book

[Tobin C. Harding]

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" <me@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 <me@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 = 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..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@tobin.cc>.
> > +
> > +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 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.

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).

thanks,
Tobin.

Re: [PATCH v2] doc: add maintainer book

[Mauro Carvalho Chehab]

Em Tue, 28 Nov 2017 07:53:03 +1100
"Tobin C. Harding" <me@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" <me@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 <me@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 = 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..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@tobin.cc>.
> > > +
> > > +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 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.
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.

Yet, I saw others that don't capitalize it.

Regards,
Mauro

Re: [PATCH v2] doc: add maintainer book

[Tobin C. Harding]

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" <me@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" <me@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 <me@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 = 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..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@tobin.cc>.
> > > > +
> > > > +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 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.