Re: [PATCH v3] doc: add maintainer book

[Jonathan Corbet]

On Thu, 30 Nov 2017 12:55:07 +1100
"Tobin C. Harding"  wrote:

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

So I've finally gotten around to giving this a look.  It seems like a good
starting point to me...send me a version with the tweaks from Mauro (and
his Reviewed-by tag) and I'll apply it.

Thanks,

jon
--
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

Re: [PATCH v3] doc: add maintainer book

[Tobin C. Harding]

On Thu, Nov 30, 2017 at 09:06:21AM -0200, Mauro Carvalho Chehab wrote:
> Em Thu, 30 Nov 2017 21:47:44 +1100
> "Tobin C. Harding"  escreveu:
> 
> > On Thu, Nov 30, 2017 at 07:01:19AM -0200, Mauro Carvalho Chehab wrote:
> > > Em Thu, 30 Nov 2017 12:55:07 +1100
> > > "Tobin C. Harding"  escreveu:
> 
> 
> > > > +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 :)
> 
> :-)
> 
> Well, if that serves as a consolation, I had to go to a dictionary to
> understand "By way of":
> 
>   https://www.collinsdictionary.com/dictionary/english/by-way-of
> 
> As that was a new expression for me :-)
> 
> Anyway, AFAIKT, English and Portuguese (and probably Spanish) have 
> similar rules with regards to commas and semicolons.

Oh cool, I didn't know that. Eu fallo um pouco Portugese muito no
esrever bem. I never learned to spell in Portuguese.

> > 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.
> 
> Yeah, that looks a way better on my eyes.

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

Re: [PATCH v3] doc: add maintainer book

[Mauro Carvalho Chehab]

Em Thu, 30 Nov 2017 21:47:44 +1100
"Tobin C. Harding"  escreveu:

> On Thu, Nov 30, 2017 at 07:01:19AM -0200, Mauro Carvalho Chehab wrote:
> > Em Thu, 30 Nov 2017 12:55:07 +1100
> > "Tobin C. Harding"  escreveu:


> > > +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 :)

:-)

Well, if that serves as a consolation, I had to go to a dictionary to
understand "By way of":

https://www.collinsdictionary.com/dictionary/english/by-way-of

As that was a new expression for me :-)

Anyway, AFAIKT, English and Portuguese (and probably Spanish) have 
similar rules with regards to commas and semicolons.

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

Yeah, that looks a way better on my eyes.

Thanks,
Mauro
--
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

Re: [PATCH v3] doc: add maintainer book

[Tobin C. Harding]

On Thu, Nov 30, 2017 at 07:01:19AM -0200, Mauro Carvalho Chehab wrote:
> Em Thu, 30 Nov 2017 12:55:07 +1100
> "Tobin C. Harding"  escreveu:
> 
> > There is currently very little documentation in the kernel on maintainer
> > level tasks. In particular there are no documents on creating pull
> > requests to submit to Linus.
> > 
> > Quoting Greg Kroah-Hartman on LKML:
> > 
> > Anyway, this actually came up at the kernel summit / maintainer
> > meeting a few weeks ago, in that "how do I make a
> > good pull request to Linus" is something we need to document.
> > 
> > Here's what I do, and it seems to work well, so maybe we should turn
> > it into the start of the documentation for how to do it.
> > 
> > (quote references: kernel summit, Europe 2017)
> > 
> > Create a new kernel documentation book 'how to be a maintainer'
> > (suggested by Jonathan Corbet). Add chapters on 'configuring git' and
> > 'creating a pull request'.
> > 
> > Most of the content was written by Linus Torvalds and Greg Kroah-Hartman
> > in discussion on LKML. This is stated at the start of one of the
> > chapters and the original email thread is referenced in
> > 'pull-requests.rst'.
> > 
> > Signed-off-by: Tobin C. Harding 
> > Reviewed-by: Greg Kroah-Hartman 
> > 
> > ---
> > 
> > v3:
> >  - Modified details for branch and tag naming, suggested by Mauro
> >Carvalho Chehab.
> >  - Added example email subject line for submitting pull requests.
> >  - Re-added Greg's reviewed-by tag from version 1.
> > 
> > v2:
> >  - Change title of book, suggested by Dan Williams.
> > 
> > ---
> >  Documentation/index.rst|   1 +
> >  Documentation/maintainer/conf.py   |  10 ++
> >  Documentation/maintainer/configure-git.rst |  34 ++
> >  Documentation/maintainer/index.rst |  10 ++
> >  Documentation/maintainer/pull-requests.rst | 182 
> > +
> >  5 files changed, 237 insertions(+)
> >  create mode 100644 Documentation/maintainer/conf.py
> >  create mode 100644 Documentation/maintainer/configure-git.rst
> >  create mode 100644 Documentation/maintainer/index.rst
> >  create mode 100644 Documentation/maintainer/pull-requests.rst
> > 
> > diff --git a/Documentation/index.rst b/Documentation/index.rst
> > index cb7f1ba5b3b1..a4fb34dddcf3 100644
> > --- a/Documentation/index.rst
> > +++ b/Documentation/index.rst
> > @@ -52,6 +52,7 @@ merged much easier.
> > dev-tools/index
> > doc-guide/index
> > kernel-hacking/index
> > +   maintainer/index
> >  
> >  Kernel API documentation
> >  
> > diff --git a/Documentation/maintainer/conf.py 
> > b/Documentation/maintainer/conf.py
> > new file mode 100644
> > index ..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 ..780d2c84
> > --- /dev/null
> > +++ b/Documentation/maintainer/configure-git.rst
> > @@ -0,0 +1,34 @@
> > +.. _configuregit:
> > +
> > +Configure Git
> > +=
> > +
> > +This chapter describes maintainer level git configuration.
> > +
> > +Tagged branches used in :ref:`Documentation/maintainer/pull-requests.rst
> > +` should be signed with the developers public GPG key. Signed
> > +tags can be created by passing the ``-u`` flag to ``git tag``. However,
> > +since you would *usually* use the same key for the same project, you can
> > +set it once with
> > +::
> > +
> > +   git config user.signingkey "keyname"
> > +
> > +Alternatively, edit your ``.git/config`` or ``~/.gitconfig`` file by hand:
> > +::
> > +
> > +   [user]
> > +   name = Jane Developer
> > +   email = 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 ..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 
> 

Re: [PATCH v3] doc: add maintainer book

[Mauro Carvalho Chehab]

Em Thu, 30 Nov 2017 12:55:07 +1100
"Tobin C. Harding"  escreveu:

> There is currently very little documentation in the kernel on maintainer
> level tasks. In particular there are no documents on creating pull
> requests to submit to Linus.
> 
> Quoting Greg Kroah-Hartman on LKML:
> 
> Anyway, this actually came up at the kernel summit / maintainer
> meeting a few weeks ago, in that "how do I make a
> good pull request to Linus" is something we need to document.
> 
> Here's what I do, and it seems to work well, so maybe we should turn
> it into the start of the documentation for how to do it.
> 
> (quote references: kernel summit, Europe 2017)
> 
> Create a new kernel documentation book 'how to be a maintainer'
> (suggested by Jonathan Corbet). Add chapters on 'configuring git' and
> 'creating a pull request'.
> 
> Most of the content was written by Linus Torvalds and Greg Kroah-Hartman
> in discussion on LKML. This is stated at the start of one of the
> chapters and the original email thread is referenced in
> 'pull-requests.rst'.
> 
> Signed-off-by: Tobin C. Harding 
> Reviewed-by: Greg Kroah-Hartman 
> 
> ---
> 
> v3:
>  - Modified details for branch and tag naming, suggested by Mauro
>Carvalho Chehab.
>  - Added example email subject line for submitting pull requests.
>  - Re-added Greg's reviewed-by tag from version 1.
> 
> v2:
>  - Change title of book, suggested by Dan Williams.
> 
> ---
>  Documentation/index.rst|   1 +
>  Documentation/maintainer/conf.py   |  10 ++
>  Documentation/maintainer/configure-git.rst |  34 ++
>  Documentation/maintainer/index.rst |  10 ++
>  Documentation/maintainer/pull-requests.rst | 182 
> +
>  5 files changed, 237 insertions(+)
>  create mode 100644 Documentation/maintainer/conf.py
>  create mode 100644 Documentation/maintainer/configure-git.rst
>  create mode 100644 Documentation/maintainer/index.rst
>  create mode 100644 Documentation/maintainer/pull-requests.rst
> 
> diff --git a/Documentation/index.rst b/Documentation/index.rst
> index cb7f1ba5b3b1..a4fb34dddcf3 100644
> --- a/Documentation/index.rst
> +++ b/Documentation/index.rst
> @@ -52,6 +52,7 @@ merged much easier.
> dev-tools/index
> doc-guide/index
> kernel-hacking/index
> +   maintainer/index
>  
>  Kernel API documentation
>  
> diff --git a/Documentation/maintainer/conf.py 
> b/Documentation/maintainer/conf.py
> new file mode 100644
> index ..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 ..780d2c84
> --- /dev/null
> +++ b/Documentation/maintainer/configure-git.rst
> @@ -0,0 +1,34 @@
> +.. _configuregit:
> +
> +Configure Git
> +=
> +
> +This chapter describes maintainer level git configuration.
> +
> +Tagged branches used in :ref:`Documentation/maintainer/pull-requests.rst
> +` should be signed with the developers public GPG key. Signed
> +tags can be created by passing the ``-u`` flag to ``git tag``. However,
> +since you would *usually* use the same key for the same project, you can
> +set it once with
> +::
> +
> + git config user.signingkey "keyname"
> +
> +Alternatively, edit your ``.git/config`` or ``~/.gitconfig`` file by hand:
> +::
> +
> + [user]
> + name = Jane Developer
> + email = 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 ..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 ..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 

[PATCH v3] 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 
Reviewed-by: Greg Kroah-Hartman 

---

v3:
 - Modified details for branch and tag naming, suggested by Mauro
   Carvalho Chehab.
 - Added example email subject line for submitting pull requests.
 - Re-added Greg's reviewed-by tag from version 1.

v2:
 - Change title of book, suggested by Dan Williams.

---
 Documentation/index.rst|   1 +
 Documentation/maintainer/conf.py   |  10 ++
 Documentation/maintainer/configure-git.rst |  34 ++
 Documentation/maintainer/index.rst |  10 ++
 Documentation/maintainer/pull-requests.rst | 182 +
 5 files changed, 237 insertions(+)
 create mode 100644 Documentation/maintainer/conf.py
 create mode 100644 Documentation/maintainer/configure-git.rst
 create mode 100644 Documentation/maintainer/index.rst
 create mode 100644 Documentation/maintainer/pull-requests.rst

diff --git a/Documentation/index.rst b/Documentation/index.rst
index cb7f1ba5b3b1..a4fb34dddcf3 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -52,6 +52,7 @@ merged much easier.
dev-tools/index
doc-guide/index
kernel-hacking/index
+   maintainer/index
 
 Kernel API documentation
 
diff --git a/Documentation/maintainer/conf.py b/Documentation/maintainer/conf.py
new file mode 100644
index ..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 ..780d2c84
--- /dev/null
+++ b/Documentation/maintainer/configure-git.rst
@@ -0,0 +1,34 @@
+.. _configuregit:
+
+Configure Git
+=
+
+This chapter describes maintainer level git configuration.
+
+Tagged branches used in :ref:`Documentation/maintainer/pull-requests.rst
+` should be signed with the developers public GPG key. Signed
+tags can be created by passing the ``-u`` flag to ``git tag``. However,
+since you would *usually* use the same key for the same project, you can
+set it once with
+::
+
+   git config user.signingkey "keyname"
+
+Alternatively, edit your ``.git/config`` or ``~/.gitconfig`` file by hand:
+::
+
+   [user]
+   name = Jane Developer
+   email = 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 ..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 ..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.