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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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@xxxxxxxxxxxxxx>
---

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

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




[Index of Archives]     [Kernel Newbies]     [Security]     [Netfilter]     [Bugtraq]     [Linux FS]     [Yosemite Forum]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Samba]     [Video 4 Linux]     [Device Mapper]     [Linux Resources]

  Powered by Linux