[PATCH 0/1] docs: process: Submitting a patch for a single git commit.

[PATCH 0/1] docs: process: Submitting a patch for a single git commit.

[Ingo Rohloff]

When I tried to submit a patch to the Linux Kernel source code
one year ago, I needed a short explanation how to submit the patch.

The code modification was already written and tested, but I did 
not know the mechanics how to submit the code modification.

I found out that "submitting-patches" unfortunately does not
tell you how to submit a patch; especially not how to submit
a minor bug-fix.

Here is a short primer trying to alleviate this particular
use case.

Ingo Rohloff (1):
  docs: process: Submitting a patch for a single git commit.

 Documentation/process/submitting-patches.rst | 72 ++++++++++++++++++++
 1 file changed, 72 insertions(+)

-- 
2.17.1

[PATCH 1/1] docs: process: Submitting a patch for a single git commit.

[Ingo Rohloff]

A short primer how to submit a single git commit as a patch via
e-mail using git send-email.

Signed-off-by: Ingo Rohloff <ingo.rohloff@lauterbach.com>
---
 Documentation/process/submitting-patches.rst | 72 ++++++++++++++++++++
 1 file changed, 72 insertions(+)

diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index 5219bf3cddfc..a73b94f677c8 100644
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -24,6 +24,8 @@ of the mechanical work done for you, though you'll still need to prepare
 and document a sensible set of patches.  In general, use of ``git`` will make
 your life as a kernel developer easier.
 
+.. _get_source_tree:
+
 0) Obtain a current source tree
 -------------------------------
 
@@ -419,6 +421,7 @@ and other kernel developers more easily distinguish patches from other
 e-mail discussions.
 
 
+.. _dev_cert_of_origin:
 
 11) Sign your work - the Developer's Certificate of Origin
 ----------------------------------------------------------
@@ -892,6 +895,75 @@ command like this will do the trick::
 
   git request-pull master git://my.public.tree/linux.git my-signed-tag
 
+17) A simple use case: Submitting a single git commit with ``git send-email``
+-----------------------------------------------------------------------------
+
+The scenario:
+You have a small code modification which sensibly fits into
+a single commit. You want to get this modification into the kernel.
+
+Assumptions:
+ - You are running a not too old Linux installation.
+ - You have ``git`` installed.
+ - You have the tools for ``git send-email`` installed.
+   It seems many Linux distributions deliver this set of tools in a
+   separate package. So make sure you have the appropriate package installed.
+   ``git send-email`` is able to directly talk to an SMTP server; so you
+   do not need a local mail transport agent or similar.
+ - You have configured ``git send-email``.
+   You might set the properties describing how you would like to send e-mail
+   via SMTP with the appropriate ``git config`` commands.
+   In particular you might need to set the properties:
+   ``sendemail.smtpserver``, ``sendemail.smtpserverport``,
+   ``sendemail.smtpuser``, ``sendemail.smtpencryption``, ``sendemail.smtppass``
+
+Process:
+ - Clone the kernel source tree; see :ref:`get_source_tree`
+ - Use ``git config`` to configure the user name and e-mail address for
+   yourself.
+ - Create and checkout a git branch to work on your code modification.
+   Use: ``git checkout -b <branch name>``
+ - Modify the code.
+ - Commit your code to your local git repository into your local branch with
+   a single commit.
+   Your commit message should start with a single line:
+   ``<subsystem>: <summary phrase>``.
+   The rest of the commit message should follow :ref:`describe_changes`
+ - Test your changes; they must compile and hopefully fix a problem.
+   If there are problems, modify your commit.
+   Use ``git commit --amend`` to modify your commit.
+ - You are now ready to generate a patch file suitable for sending via e-mail.
+   Use::
+
+	git format-patch -1 -s
+
+   This command should create a patch file, which is close to what you need
+   to send via e-mail.
+   This command also adds a "Signed-off-by:" line; see
+   :ref:`the_canonical_patch_format`, and :ref:`dev_cert_of_origin`.
+ - Verify that your patch matches the required style::
+
+	./scripts/checkpatch.pl <patch file>
+
+   Also see :ref:`Documentation/process/coding-style.rst <codingstyle>`.
+   If there are problems, modify your commit (``git commit --amend``)
+   and subsequently your e-mail patch (``git format-patch``).
+ - Test if you are able to send the patch to yourself::
+
+	git send-email --to=<your email address> <patch file>
+
+ - If sending the e-mail to yourself worked, inspect the e-mail you have
+   received and check if it adheres to :ref:`the_canonical_patch_format`.
+ - Find out to which people the e-mail should be send::
+
+	./scripts/get_maintainer.pl <patch file>
+
+   In general send the e-mail to the appropriate maintainer and put relevant
+   mailing lists on CC.
+ - Finally send the patch e-mail with::
+
+	git send-email --to=<maintainer> --cc=<mail list 1> ... <patch file>
+
 
 References
 ----------
-- 
2.17.1

Re: [PATCH 1/1] docs: process: Submitting a patch for a single git commit.

[Jonathan Corbet]

On Thu,  1 Oct 2020 12:47:24 +0200
Ingo Rohloff <ingo.rohloff@lauterbach.com> wrote:

> A short primer how to submit a single git commit as a patch via
> e-mail using git send-email.
> 
> Signed-off-by: Ingo Rohloff <ingo.rohloff@lauterbach.com>
> ---
>  Documentation/process/submitting-patches.rst | 72 ++++++++++++++++++++
>  1 file changed, 72 insertions(+)

So I still don't think that this is appropriate for submitting-patches.rst,
which is already far too long.  It *might* be useful if it were filled out
and added as a separate tutorial document, though.

A few minor comments below...

> diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
> index 5219bf3cddfc..a73b94f677c8 100644
> --- a/Documentation/process/submitting-patches.rst
> +++ b/Documentation/process/submitting-patches.rst
> @@ -24,6 +24,8 @@ of the mechanical work done for you, though you'll still need to prepare
>  and document a sensible set of patches.  In general, use of ``git`` will make
>  your life as a kernel developer easier.
>  
> +.. _get_source_tree:
> +
>  0) Obtain a current source tree
>  -------------------------------
>  
> @@ -419,6 +421,7 @@ and other kernel developers more easily distinguish patches from other
>  e-mail discussions.
>  
>  
> +.. _dev_cert_of_origin:
>  
>  11) Sign your work - the Developer's Certificate of Origin
>  ----------------------------------------------------------
> @@ -892,6 +895,75 @@ command like this will do the trick::
>  
>    git request-pull master git://my.public.tree/linux.git my-signed-tag
>  
> +17) A simple use case: Submitting a single git commit with ``git send-email``
> +-----------------------------------------------------------------------------
> +
> +The scenario:
> +You have a small code modification which sensibly fits into
> +a single commit. You want to get this modification into the kernel.
> +
> +Assumptions:
> + - You are running a not too old Linux installation.

What is "too old"?  Somebody who needs a tutorial at this level is unlikely
to know that.

> + - You have ``git`` installed.
> + - You have the tools for ``git send-email`` installed.
> +   It seems many Linux distributions deliver this set of tools in a
> +   separate package. So make sure you have the appropriate package installed.
> +   ``git send-email`` is able to directly talk to an SMTP server; so you
> +   do not need a local mail transport agent or similar.
> + - You have configured ``git send-email``.
> +   You might set the properties describing how you would like to send e-mail
> +   via SMTP with the appropriate ``git config`` commands.
> +   In particular you might need to set the properties:
> +   ``sendemail.smtpserver``, ``sendemail.smtpserverport``,
> +   ``sendemail.smtpuser``, ``sendemail.smtpencryption``, ``sendemail.smtppass``

That's an awful lot of configuration that has just been skipped over...

> +Process:
> + - Clone the kernel source tree; see :ref:`get_source_tree`
> + - Use ``git config`` to configure the user name and e-mail address for
> +   yourself.

If we're going to make a tutorial, actually say how to do that.

> + - Create and checkout a git branch to work on your code modification.
> +   Use: ``git checkout -b <branch name>``
> + - Modify the code.
> + - Commit your code to your local git repository into your local branch with
> +   a single commit.
> +   Your commit message should start with a single line:
> +   ``<subsystem>: <summary phrase>``.
> +   The rest of the commit message should follow :ref:`describe_changes`
> + - Test your changes; they must compile and hopefully fix a problem.

Why on earth would you commit your changes before you test them?

> +   If there are problems, modify your commit.
> +   Use ``git commit --amend`` to modify your commit.
> + - You are now ready to generate a patch file suitable for sending via e-mail.
> +   Use::
> +
> +	git format-patch -1 -s
> +
> +   This command should create a patch file, which is close to what you need
> +   to send via e-mail.
> +   This command also adds a "Signed-off-by:" line; see
> +   :ref:`the_canonical_patch_format`, and :ref:`dev_cert_of_origin`.

Why wouldn't you put the signoff in the commit?

> + - Verify that your patch matches the required style::
> +
> +	./scripts/checkpatch.pl <patch file>
> +
> +   Also see :ref:`Documentation/process/coding-style.rst <codingstyle>`.
> +   If there are problems, modify your commit (``git commit --amend``)
> +   and subsequently your e-mail patch (``git format-patch``).
> + - Test if you are able to send the patch to yourself::
> +
> +	git send-email --to=<your email address> <patch file>
> +
> + - If sending the e-mail to yourself worked, inspect the e-mail you have
> +   received and check if it adheres to :ref:`the_canonical_patch_format`.

Haven't you already ensured that you've formatted it correctly?

> + - Find out to which people the e-mail should be send::
> +
> +	./scripts/get_maintainer.pl <patch file>
> +
> +   In general send the e-mail to the appropriate maintainer and put relevant
> +   mailing lists on CC.
> + - Finally send the patch e-mail with::
> +
> +	git send-email --to=<maintainer> --cc=<mail list 1> ... <patch file>
> +

Thanks,

jon

Re: [PATCH 1/1] docs: process: Submitting a patch for a single git commit.

[Ingo Rohloff]

Hello,

On Fri, 9 Oct 2020 09:46:58 -0600
Jonathan Corbet <corbet@lwn.net> wrote:

> On Thu,  1 Oct 2020 12:47:24 +0200
> Ingo Rohloff <ingo.rohloff@lauterbach.com> wrote:
> 
> > A short primer how to submit a single git commit as a patch via
> > e-mail using git send-email.
> > 
> > Signed-off-by: Ingo Rohloff <ingo.rohloff@lauterbach.com>
> > ---
> >  Documentation/process/submitting-patches.rst | 72 ++++++++++++++++++++
> >  1 file changed, 72 insertions(+)  
> 
> So I still don't think that this is appropriate for submitting-patches.rst,
> which is already far too long.  It *might* be useful if it were filled out
> and added as a separate tutorial document, though.

"submitting-patches.rst" does not answer "how to submit a patch ?".
70% of the material is about how a patch should look like and how
to react once you have submitted a patch.
The most important tool for *submitting* a patch (git send-email)
is missing completely (only mentioned in a side note).

If you want to get "submitting-patches.rst" shorter, move the material, 
which does not deal with "how to submit a patch", to somewhere else.

> > +Assumptions:
> > + - You are running a not too old Linux installation.  
> 
> What is "too old"?  Somebody who needs a tutorial at this level is unlikely
> to know that.
> 

It means *YOU* are able to work with the machine comfortably
( == you are able to use git, you are able to edit the source code,
you are able to compile the kernel, ...)
This probably will not be the case for a 10 year old computer running a 2.6 kernel.
But this is subjective; hence why I wrote "not too old" (== not too old for YOU).


> > + - You have configured ``git send-email``.
> > +   You might set the properties describing how you would like to send e-mail
> > +   via SMTP with the appropriate ``git config`` commands.
> > +   In particular you might need to set the properties:
> > +   ``sendemail.smtpserver``, ``sendemail.smtpserverport``,
> > +   ``sendemail.smtpuser``, ``sendemail.smtpencryption``, ``sendemail.smtppass``  
> 
> That's an awful lot of configuration that has just been skipped over...
> 

That's exactly the same kind of configuration I need when setting up 
any other E-Mail client without using a wizard.
"submitting-patches.rst" assumes that you are able to setup your E-Mail client.

"git send-email" needs less configuration than setting up a regular E-Mail client,
because the configuration for receiving Mail is not needed.


> > +Process:
> > + - Clone the kernel source tree; see :ref:`get_source_tree`
> > + - Use ``git config`` to configure the user name and e-mail address for
> > +   yourself.  
> 
> If we're going to make a tutorial, actually say how to do that.
> 

This is *NOT* a tutorial.
The text I wrote is trying to answer the question "how to submit a patch ?".
I expect readers to be able to type
  git configure e-mail address
into Google.

As contrast: Right now if I type
  linux kernel submit patch
into Google I get "submitting-patches.rst" as first hit;
and I get no information at all that "git send-email" is 
the right tool to submit a patch.

> > + - Commit your code to your local git repository into your local branch with
> > +   a single commit.
> > +   Your commit message should start with a single line:
> > +   ``<subsystem>: <summary phrase>``.
> > +   The rest of the commit message should follow :ref:`describe_changes`
> > + - Test your changes; they must compile and hopefully fix a problem.  
> 
> Why on earth would you commit your changes before you test them?
> 

Because this is a local git repository.
The whole point in using git is to be able to save
intermediate steps (via "git commit").
You have to cleanup the code modifications before you *publish* them;
but not while you are creating them.

> > + - You are now ready to generate a patch file suitable for sending via e-mail.
> > +   Use::
> > +
> > +	git format-patch -1 -s
> > +
> > +   This command should create a patch file, which is close to what you need
> > +   to send via e-mail.
> > +   This command also adds a "Signed-off-by:" line; see
> > +   :ref:`the_canonical_patch_format`, and :ref:`dev_cert_of_origin`.  
> 
> Why wouldn't you put the signoff in the commit?
> 

Because this is a local git repository.
I expect to have a few iterations, before I am satisfied with the modification.
I do not want to put a sign-off on each local iteration, because that's a waste of time.
I add the sign-off once I am ready to publish (via "git format-patch").

> > + - If sending the e-mail to yourself worked, inspect the e-mail you have
> > +   received and check if it adheres to :ref:`the_canonical_patch_format`.  
> 
> Haven't you already ensured that you've formatted it correctly?
> 

E-Mail programs tend to garble E-Mails (which is already mentioned
in "submitting-patches.rst").
If you want to make sure, that the ASCII content is completely 
unmodified, the only way to find out if that works is to send 
an E-Mail to yourself and inspect it.

That's also why I think "git send-email" is the only reliable
approach to submit a patch; all the other well-known E-Mail programs
are painful, if you want to make sure the ASCII content is not touched
(maybe "mutt" is one of the few exceptions).
If you are behind a corporate SMTP server, then I guess the SMTP server 
itself might STILL modify your E-Mail :-(
(like adding a mandatory "signature"...)

"git send-email" knows how to translate the output
of "git format-patch" into an E-Mail.

In "submitting-patches.rst" it says:
  proper patch formatting can be had with git format-patch

This is misleading.
For sure you *should not* paste or attach the output of 
"git format-patch" into your E-Mail program verbatim.


so long
  Ingo