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

[Jonathan Corbet <corbet@lwn.net>]

On Fri, 11 Oct 2019 18:33:58 +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>
> ---
> 
> Notes:
>     I just went through this process and did a lot of mistakes,
>     because I was confused how git commits translate to patches via e-mail.
>     
>     So I thought maybe writing down a very small primer how to submit
>     a single git commit via e-mail employing "git send-email" might
>     be a good idea.
>     
>     I probably still have no clue how to do that correctly; so the primer
>     might have wrong information. Additionally I am not an English native
>     speaker so the language might be less than optimal.
>     
>     What do you think ?
> 
>  Documentation/process/submitting-patches.rst | 63 ++++++++++++++++++++
>  1 file changed, 63 insertions(+)

I think we should find a place for this kind of information, but I don't
think submitting-patches.rst is it.  That's meant to be a comprehensive set
of rules and guidelines; it's already far too long as it is.  A separate
document with introductory tutorials might be a good idea.

> diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
> index fb56297f70dc..b00518584810 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
>  -------------------------------
>  
> @@ -836,6 +838,67 @@ 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's "not too old"?  A reader who needs documentation at this level will
not have an answer to that question.

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

This, too, will not be helpful to somebody needing this kind of
documentation.  We should actually tell them how to do this configuration. 

> +   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``

This is a start, but many readers at this level won't really know what this
means.  

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

Examples are good for this kind of thing.

Also, watch your line lengths; there's no reason to go over 80 columns for
this kind of text.  You tell people to run checkpatch but didn't do it :)

> + - 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`

So much of this would work better with an example.

> + - Test your changes; they must compile and hopefully fix a problem.

"hopefully"?

Honestly, you probably want to test your changes before you start
committing things and writing changelogs.

> +   If there are problems, modify your commit.
> +   Use ``git commit --amend`` to modify your commit.

...again...  why would you commit untested changes?

> + - 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`

Normally one adds the signoff when committing.

> + - Verify that your patch matches the required style::
> +
> +	./scripts/checkpatch.pl <patch file>
> +
> +   If there are problems, modify your commit and subsequently your e-mail 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`.

This is late to be sure you have your changelog formatted correctly.

It can be good advice to tell people to ensure that the patch can be
applied.  git send-email shouldn't corrupt patches, though.

> + - 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=<mailing list 1> --cc=<mailing list 2> ...
> +
>  
>  References
>  ----------

Thanks for working to improve our documentation!  I think there can be
value in something like this, once it gets into shape.

jon