* [PATCH 0/1] docs: process: Submitting a patch for a single git commit. @ 2020-10-01 10:47 Ingo Rohloff 2020-10-01 10:47 ` [PATCH 1/1] " Ingo Rohloff 0 siblings, 1 reply; 4+ messages in thread From: Ingo Rohloff @ 2020-10-01 10:47 UTC (permalink / raw) To: corbet; +Cc: linux-doc, 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 ^ permalink raw reply [flat|nested] 4+ messages in thread
* [PATCH 1/1] docs: process: Submitting a patch for a single git commit. 2020-10-01 10:47 [PATCH 0/1] docs: process: Submitting a patch for a single git commit Ingo Rohloff @ 2020-10-01 10:47 ` Ingo Rohloff 2020-10-09 15:46 ` Jonathan Corbet 0 siblings, 1 reply; 4+ messages in thread From: Ingo Rohloff @ 2020-10-01 10:47 UTC (permalink / raw) To: corbet; +Cc: linux-doc, 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 ^ permalink raw reply related [flat|nested] 4+ messages in thread
* Re: [PATCH 1/1] docs: process: Submitting a patch for a single git commit. 2020-10-01 10:47 ` [PATCH 1/1] " Ingo Rohloff @ 2020-10-09 15:46 ` Jonathan Corbet 2020-10-12 10:00 ` Ingo Rohloff 0 siblings, 1 reply; 4+ messages in thread From: Jonathan Corbet @ 2020-10-09 15:46 UTC (permalink / raw) To: Ingo Rohloff; +Cc: linux-doc 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 ^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [PATCH 1/1] docs: process: Submitting a patch for a single git commit. 2020-10-09 15:46 ` Jonathan Corbet @ 2020-10-12 10:00 ` Ingo Rohloff 0 siblings, 0 replies; 4+ messages in thread From: Ingo Rohloff @ 2020-10-12 10:00 UTC (permalink / raw) To: Jonathan Corbet; +Cc: linux-doc 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 ^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2020-10-12 10:00 UTC | newest] Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2020-10-01 10:47 [PATCH 0/1] docs: process: Submitting a patch for a single git commit Ingo Rohloff 2020-10-01 10:47 ` [PATCH 1/1] " Ingo Rohloff 2020-10-09 15:46 ` Jonathan Corbet 2020-10-12 10:00 ` Ingo Rohloff
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.