[PATCH 0/4] Improvements to submitting-patches.rst

[PATCH 0/4] Improvements to submitting-patches.rst

[Drew DeVault]

This patch series updates submitting-patches.rst, streamlining it for
git usage, re-homing some of the content to better locations, and
updating it to follow the modern conventions of Documentation/.

This is a revision to <20200827174237.121004-1-sir@cmpwn.com>.

Drew DeVault (4):
  submitting-patches.rst: remove heading numbering
  Documentation/process: expand plain-text advice
  Documentation/maintainer: rehome sign-off process
  submitting-patches.rst: presume git will be used

 Documentation/maintainer/index.rst            |   1 +
 .../maintainer/modifying-patches.rst          |  50 ++++++
 Documentation/process/email-clients.rst       |   5 +
 Documentation/process/submitting-patches.rst  | 170 +++++-------------
 4 files changed, 96 insertions(+), 130 deletions(-)
 create mode 100644 Documentation/maintainer/modifying-patches.rst

-- 
2.28.0

[PATCH 1/4] submitting-patches.rst: remove heading numbering

[Drew DeVault]

This follows similar changes throughout Documentation; these numbers
tend to get outdated and are not especially useful.

Signed-off-by: Drew DeVault <sir@cmpwn.com>
---
 Documentation/process/submitting-patches.rst | 30 ++++++++++----------
 1 file changed, 15 insertions(+), 15 deletions(-)

diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index 5219bf3cddfc..f205753ae3d8 100644
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -24,7 +24,7 @@ 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.
 
-0) Obtain a current source tree
+Obtain a current source tree
 -------------------------------
 
 If you do not have a repository with the current kernel source handy, use
@@ -99,7 +99,7 @@ is another popular alternative.
 
 .. _describe_changes:
 
-2) Describe your changes
+Describe your changes
 ------------------------
 
 Describe your problem.  Whether your patch is a one-line bug fix or
@@ -203,7 +203,7 @@ An example call::
 
 .. _split_changes:
 
-3) Separate your changes
+Separate your changes
 ------------------------
 
 Separate each **logical change** into a separate patch.
@@ -236,7 +236,7 @@ then only post say 15 or so at a time and wait for review and integration.
 
 
 
-4) Style-check your changes
+Style-check your changes
 ---------------------------
 
 Check your patch for basic style violations, details of which can be
@@ -267,7 +267,7 @@ You should be able to justify all violations that remain in your
 patch.
 
 
-5) Select the recipients for your patch
+Select the recipients for your patch
 ---------------------------------------
 
 You should always copy the appropriate subsystem maintainer(s) on any patch
@@ -342,7 +342,7 @@ Trivial patches must qualify for one of the following rules:
 
 
 
-6) No MIME, no links, no compression, no attachments.  Just plain text
+No MIME, no links, no compression, no attachments.  Just plain text
 ----------------------------------------------------------------------
 
 Linus and other kernel developers need to be able to read and comment
@@ -370,7 +370,7 @@ See :ref:`Documentation/process/email-clients.rst <email_clients>`
 for hints about configuring your e-mail client so that it sends your patches
 untouched.
 
-7) E-mail size
+E-mail size
 --------------
 
 Large changes are not appropriate for mailing lists, and some
@@ -396,7 +396,7 @@ reviewers sometimes get grumpy.  Even in that case, though, respond
 politely and address the problems they have pointed out.
 
 
-9) Don't get discouraged - or impatient
+Don't get discouraged - or impatient
 ---------------------------------------
 
 After you have submitted your change, be patient and wait.  Reviewers are
@@ -410,7 +410,7 @@ one week before resubmitting or pinging reviewers - possibly longer during
 busy times like merge windows.
 
 
-10) Include PATCH in the subject
+Include PATCH in the subject
 --------------------------------
 
 Due to high e-mail traffic to Linus, and to linux-kernel, it is common
@@ -420,7 +420,7 @@ e-mail discussions.
 
 
 
-11) Sign your work - the Developer's Certificate of Origin
+Sign your work - the Developer's Certificate of Origin
 ----------------------------------------------------------
 
 To improve tracking of who did what, especially with patches that can
@@ -586,7 +586,7 @@ Example of a patch submitted by a Co-developed-by: author::
 	Signed-off-by: Submitting Co-Author <sub@coauthor.example.org>
 
 
-13) Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes:
+Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes:
 --------------------------------------------------------------------------
 
 The Reported-by tag gives credit to people who find bugs and report them and it
@@ -650,7 +650,7 @@ for more details.
 
 .. _the_canonical_patch_format:
 
-14) The canonical patch format
+The canonical patch format
 ------------------------------
 
 This section describes how the patch itself should be formatted.  Note
@@ -773,7 +773,7 @@ references.
 
 .. _explicit_in_reply_to:
 
-15) Explicit In-Reply-To headers
+Explicit In-Reply-To headers
 --------------------------------
 
 It can be helpful to manually add In-Reply-To: headers to a patch
@@ -787,7 +787,7 @@ helpful, you can use the https://lkml.kernel.org/ redirector (e.g., in
 the cover email text) to link to an earlier version of the patch series.
 
 
-16) Providing base tree information
+Providing base tree information
 -----------------------------------
 
 When other developers receive your patches and start the review process,
@@ -838,7 +838,7 @@ either below the ``---`` line or at the very bottom of all other
 content, right before your email signature.
 
 
-17) Sending ``git pull`` requests
+Sending ``git pull`` requests
 ---------------------------------
 
 If you have a series of patches, it may be most convenient to have the
-- 
2.28.0

Re: [PATCH 1/4] submitting-patches.rst: remove heading numbering

[Jonathan Corbet]

On Wed,  2 Sep 2020 11:57:56 -0400
Drew DeVault <sir@cmpwn.com> wrote:

> -11) Sign your work - the Developer's Certificate of Origin
> +Sign your work - the Developer's Certificate of Origin
>  ----------------------------------------------------------
>  
>  To improve tracking of who did what, especially with patches that can
> @@ -586,7 +586,7 @@ Example of a patch submitted by a Co-developed-by: author::
>  	Signed-off-by: Submitting Co-Author <sub@coauthor.example.org>
>  
>  
> -13) Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes:
> +Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes:
>  --------------------------------------------------------------------------

So why skip section 12 here?  You get to that in a later patch, where it
becomes an unrelated change; it would be better to finish that task here.

Thanks,

jon

Re: [PATCH 1/4] submitting-patches.rst: remove heading numbering

[Drew DeVault]

On Thu Sep 3, 2020 at 11:44 AM EDT, Jonathan Corbet wrote:
> So why skip section 12 here? You get to that in a later patch, where it
> becomes an unrelated change; it would be better to finish that task
> here.

Whoops, user error splitting up the patches. Sorry for the headache.

Re: [PATCH 1/4] submitting-patches.rst: remove heading numbering

[Jonathan Corbet]

One other picky little detail...

On Wed,  2 Sep 2020 11:57:56 -0400
Drew DeVault <sir@cmpwn.com> wrote:

> -0) Obtain a current source tree
> +Obtain a current source tree
>  -------------------------------

Please adjust the length of the "---------" line to match the new headers.

Thanks,

jon

[PATCH 2/4] Documentation/process: expand plain-text advice

[Drew DeVault]

This adds a link to https://useplaintext.email to email-clients.rst,
which is a more exhaustive resource on configuring various mail clients
for plain text use. submitting-patches.rst is also updated to direct
readers to email-clients.rst to equip new contributors with the
requisite knowledge to become a good participant on the mailing lists.

Signed-off-by: Drew DeVault <sir@cmpwn.com>
---
Conflict of interest: I wrote and maintain the website this links to.

 Documentation/process/email-clients.rst      | 5 +++++
 Documentation/process/submitting-patches.rst | 3 +++
 2 files changed, 8 insertions(+)

diff --git a/Documentation/process/email-clients.rst b/Documentation/process/email-clients.rst
index c9e4ce2613c0..16586f6cc888 100644
--- a/Documentation/process/email-clients.rst
+++ b/Documentation/process/email-clients.rst
@@ -25,6 +25,11 @@ attachments, but then the attachments should have content-type
 it makes quoting portions of the patch more difficult in the patch
 review process.
 
+It's also strongly recommended that you use plain text in your email body,
+for patches and other emails alike. https://useplaintext.email may be useful
+for information on how to configure your preferred email client, as well as
+listing recommended email clients should you not already have a preference.
+
 Email clients that are used for Linux kernel patches should send the
 patch text untouched.  For example, they should not modify or delete tabs
 or spaces, even at the beginning or end of lines.
diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index f205753ae3d8..0dec104cb932 100644
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -395,6 +395,9 @@ for their time.  Code review is a tiring and time-consuming process, and
 reviewers sometimes get grumpy.  Even in that case, though, respond
 politely and address the problems they have pointed out.
 
+See :ref:`Documentation/process/email-clients.rst` for recommendations on email
+clients and mailing list etiquette.
+
 
 Don't get discouraged - or impatient
 ---------------------------------------
-- 
2.28.0

Re: [PATCH 2/4] Documentation/process: expand plain-text advice

[Randy Dunlap]

On 9/2/20 8:57 AM, Drew DeVault wrote:
> This adds a link to https://useplaintext.email to email-clients.rst,
> which is a more exhaustive resource on configuring various mail clients
> for plain text use. submitting-patches.rst is also updated to direct
> readers to email-clients.rst to equip new contributors with the
> requisite knowledge to become a good participant on the mailing lists.
> 
> Signed-off-by: Drew DeVault <sir@cmpwn.com>
> ---
> Conflict of interest: I wrote and maintain the website this links to.
> 
>  Documentation/process/email-clients.rst      | 5 +++++
>  Documentation/process/submitting-patches.rst | 3 +++
>  2 files changed, 8 insertions(+)
> 
> diff --git a/Documentation/process/email-clients.rst b/Documentation/process/email-clients.rst
> index c9e4ce2613c0..16586f6cc888 100644
> --- a/Documentation/process/email-clients.rst
> +++ b/Documentation/process/email-clients.rst
> @@ -25,6 +25,11 @@ attachments, but then the attachments should have content-type
>  it makes quoting portions of the patch more difficult in the patch
>  review process.
>  
> +It's also strongly recommended that you use plain text in your email body,
> +for patches and other emails alike. https://useplaintext.email may be useful

You could justify that first sentence by adding that some mailing lists drop/discard
emails that are in html.

> +for information on how to configure your preferred email client, as well as
> +listing recommended email clients should you not already have a preference.
> +
>  Email clients that are used for Linux kernel patches should send the
>  patch text untouched.  For example, they should not modify or delete tabs
>  or spaces, even at the beginning or end of lines.
> diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
> index f205753ae3d8..0dec104cb932 100644
> --- a/Documentation/process/submitting-patches.rst
> +++ b/Documentation/process/submitting-patches.rst
> @@ -395,6 +395,9 @@ for their time.  Code review is a tiring and time-consuming process, and
>  reviewers sometimes get grumpy.  Even in that case, though, respond
>  politely and address the problems they have pointed out.
>  
> +See :ref:`Documentation/process/email-clients.rst` for recommendations on email
> +clients and mailing list etiquette.
> +
>  
>  Don't get discouraged - or impatient
>  ---------------------------------------
> 

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>

-- 
~Randy

Re: [PATCH 2/4] Documentation/process: expand plain-text advice

[Drew DeVault]

On Wed Sep 2, 2020 at 12:06 PM EDT, Randy Dunlap wrote:
> On 9/2/20 8:57 AM, Drew DeVault wrote:
> > This adds a link to https://useplaintext.email to email-clients.rst,
> > which is a more exhaustive resource on configuring various mail clients
> > for plain text use. submitting-patches.rst is also updated to direct
> > readers to email-clients.rst to equip new contributors with the
> > requisite knowledge to become a good participant on the mailing lists.
> > 
> > Signed-off-by: Drew DeVault <sir@cmpwn.com>
> > ---
> > Conflict of interest: I wrote and maintain the website this links to.
> > 
> >  Documentation/process/email-clients.rst      | 5 +++++
> >  Documentation/process/submitting-patches.rst | 3 +++
> >  2 files changed, 8 insertions(+)
> > 
> > diff --git a/Documentation/process/email-clients.rst b/Documentation/process/email-clients.rst
> > index c9e4ce2613c0..16586f6cc888 100644
> > --- a/Documentation/process/email-clients.rst
> > +++ b/Documentation/process/email-clients.rst
> > @@ -25,6 +25,11 @@ attachments, but then the attachments should have content-type
> >  it makes quoting portions of the patch more difficult in the patch
> >  review process.
> >  
> > +It's also strongly recommended that you use plain text in your email body,
> > +for patches and other emails alike. https://useplaintext.email may be useful
>
> You could justify that first sentence by adding that some mailing
> lists drop/discard emails that are in html.

Will add this if the patch ends up being re-rolled, but I don't think it
necessarily warrants a v3.

Re: [PATCH 2/4] Documentation/process: expand plain-text advice

[Jonathan Corbet]

On Wed,  2 Sep 2020 11:57:57 -0400
Drew DeVault <sir@cmpwn.com> wrote:

> This adds a link to https://useplaintext.email to email-clients.rst,
> which is a more exhaustive resource on configuring various mail clients
> for plain text use. submitting-patches.rst is also updated to direct
> readers to email-clients.rst to equip new contributors with the
> requisite knowledge to become a good participant on the mailing lists.
> 
> Signed-off-by: Drew DeVault <sir@cmpwn.com>

This one seems good to me; it doesn't quite apply without patch 1, but
it's otherwise ready to go, I think.

Thanks,

jon

[PATCH 3/4] Documentation/maintainer: rehome sign-off process

[Drew DeVault]

The repeated sign-offs necessary when a subsystem maintainer modifies an
incoming patch has been moved from submitting-patches.rst to
Documentation/maintainer, since the affairs of a subsystem maintainer
are not especially relevant to someone reading a guide for how to submit
their first patch.

Signed-off-by: Drew DeVault <sir@cmpwn.com>
---
 Documentation/maintainer/index.rst            |  1 +
 .../maintainer/modifying-patches.rst          | 50 +++++++++++++++++++
 Documentation/process/submitting-patches.rst  | 46 -----------------
 3 files changed, 51 insertions(+), 46 deletions(-)
 create mode 100644 Documentation/maintainer/modifying-patches.rst

diff --git a/Documentation/maintainer/index.rst b/Documentation/maintainer/index.rst
index d904e74e1159..f0a60435b124 100644
--- a/Documentation/maintainer/index.rst
+++ b/Documentation/maintainer/index.rst
@@ -13,4 +13,5 @@ additions to this manual.
    rebasing-and-merging
    pull-requests
    maintainer-entry-profile
+   modifying-patches
 
diff --git a/Documentation/maintainer/modifying-patches.rst b/Documentation/maintainer/modifying-patches.rst
new file mode 100644
index 000000000000..d7c3f557bf6e
--- /dev/null
+++ b/Documentation/maintainer/modifying-patches.rst
@@ -0,0 +1,50 @@
+.. _modifyingpatches:
+
+Modifying Patches
+=================
+
+If you are a subsystem or branch maintainer, sometimes you need to slightly
+modify patches you receive in order to merge them, because the code is not
+exactly the same in your tree and the submitters'. If you stick strictly to
+rule (c), you should ask the submitter to rediff, but this is a totally
+counter-productive waste of time and energy. Rule (b) allows you to adjust
+the code, but then it is very impolite to change one submitter's code and
+make him endorse your bugs. To solve this problem, it is recommended that
+you add a line between the last Signed-off-by header and yours, indicating
+the nature of your changes. While there is nothing mandatory about this, it
+seems like prepending the description with your mail and/or name, all
+enclosed in square brackets, is noticeable enough to make it obvious that
+you are responsible for last-minute changes. Example::
+
+       Signed-off-by: Random J Developer <random@developer.example.org>
+       [lucky@maintainer.example.org: struct foo moved from foo.c to foo.h]
+       Signed-off-by: Lucky K Maintainer <lucky@maintainer.example.org>
+
+This practice is particularly helpful if you maintain a stable branch and
+want at the same time to credit the author, track changes, merge the fix,
+and protect the submitter from complaints. Note that under no circumstances
+can you change the author's identity (the From header), as it is the one
+which appears in the changelog.
+
+Special note to back-porters: It seems to be a common and useful practice
+to insert an indication of the origin of a patch at the top of the commit
+message (just after the subject line) to facilitate tracking. For instance,
+here's what we see in a 3.x-stable release::
+
+  Date:   Tue Oct 7 07:26:38 2014 -0400
+
+    libata: Un-break ATA blacklist
+
+    commit 1c40279960bcd7d52dbdf1d466b20d24b99176c8 upstream.
+
+And here's what might appear in an older kernel once a patch is backported::
+
+    Date:   Tue May 13 22:12:27 2008 +0200
+
+        wireless, airo: waitbusy() won't delay
+
+        [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a]
+
+Whatever the format, this information provides a valuable help to people
+tracking your trees, and to people trying to troubleshoot bugs in your
+tree.
diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index 0dec104cb932..dd008b89bca5 100644
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -473,52 +473,6 @@ Some people also put extra tags at the end.  They'll just be ignored for
 now, but you can do this to mark internal company procedures or just
 point out some special detail about the sign-off.
 
-If you are a subsystem or branch maintainer, sometimes you need to slightly
-modify patches you receive in order to merge them, because the code is not
-exactly the same in your tree and the submitters'. If you stick strictly to
-rule (c), you should ask the submitter to rediff, but this is a totally
-counter-productive waste of time and energy. Rule (b) allows you to adjust
-the code, but then it is very impolite to change one submitter's code and
-make him endorse your bugs. To solve this problem, it is recommended that
-you add a line between the last Signed-off-by header and yours, indicating
-the nature of your changes. While there is nothing mandatory about this, it
-seems like prepending the description with your mail and/or name, all
-enclosed in square brackets, is noticeable enough to make it obvious that
-you are responsible for last-minute changes. Example::
-
-	Signed-off-by: Random J Developer <random@developer.example.org>
-	[lucky@maintainer.example.org: struct foo moved from foo.c to foo.h]
-	Signed-off-by: Lucky K Maintainer <lucky@maintainer.example.org>
-
-This practice is particularly helpful if you maintain a stable branch and
-want at the same time to credit the author, track changes, merge the fix,
-and protect the submitter from complaints. Note that under no circumstances
-can you change the author's identity (the From header), as it is the one
-which appears in the changelog.
-
-Special note to back-porters: It seems to be a common and useful practice
-to insert an indication of the origin of a patch at the top of the commit
-message (just after the subject line) to facilitate tracking. For instance,
-here's what we see in a 3.x-stable release::
-
-  Date:   Tue Oct 7 07:26:38 2014 -0400
-
-    libata: Un-break ATA blacklist
-
-    commit 1c40279960bcd7d52dbdf1d466b20d24b99176c8 upstream.
-
-And here's what might appear in an older kernel once a patch is backported::
-
-    Date:   Tue May 13 22:12:27 2008 +0200
-
-        wireless, airo: waitbusy() won't delay
-
-        [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a]
-
-Whatever the format, this information provides a valuable help to people
-tracking your trees, and to people trying to troubleshoot bugs in your
-tree.
-
 
 12) When to use Acked-by:, Cc:, and Co-developed-by:
 -------------------------------------------------------
-- 
2.28.0

Re: [PATCH 3/4] Documentation/maintainer: rehome sign-off process

[Jonathan Corbet]

On Wed,  2 Sep 2020 11:57:58 -0400
Drew DeVault <sir@cmpwn.com> wrote:

> The repeated sign-offs necessary when a subsystem maintainer modifies an
> incoming patch has been moved from submitting-patches.rst to
> Documentation/maintainer, since the affairs of a subsystem maintainer
> are not especially relevant to someone reading a guide for how to submit
> their first patch.

So this is generally what I wanted, but...

> Signed-off-by: Drew DeVault <sir@cmpwn.com>
> ---
>  Documentation/maintainer/index.rst            |  1 +
>  .../maintainer/modifying-patches.rst          | 50 +++++++++++++++++++
>  Documentation/process/submitting-patches.rst  | 46 -----------------
>  3 files changed, 51 insertions(+), 46 deletions(-)
>  create mode 100644 Documentation/maintainer/modifying-patches.rst
> 
> diff --git a/Documentation/maintainer/index.rst b/Documentation/maintainer/index.rst
> index d904e74e1159..f0a60435b124 100644
> --- a/Documentation/maintainer/index.rst
> +++ b/Documentation/maintainer/index.rst
> @@ -13,4 +13,5 @@ additions to this manual.
>     rebasing-and-merging
>     pull-requests
>     maintainer-entry-profile
> +   modifying-patches
>  
> diff --git a/Documentation/maintainer/modifying-patches.rst b/Documentation/maintainer/modifying-patches.rst
> new file mode 100644
> index 000000000000..d7c3f557bf6e
> --- /dev/null
> +++ b/Documentation/maintainer/modifying-patches.rst
> @@ -0,0 +1,50 @@
> +.. _modifyingpatches:
> +
> +Modifying Patches
> +=================
> +
> +If you are a subsystem or branch maintainer, sometimes you need to slightly
> +modify patches you receive in order to merge them, because the code is not
> +exactly the same in your tree and the submitters'. If you stick strictly to
> +rule (c), you should ask the submitter to rediff, but this is a totally

"rule (c)" has not context here; readers won't know what is being talked
about.  At a minimum, it should be "rule (c) of the developers certificate
of origin".

Also, "submitter's", might as well fix it while you're at it.

Thanks,

jon

[PATCH 4/4] submitting-patches.rst: presume git will be used

[Drew DeVault]

Git is fairly ubiquitous these days, and the additional information in
this documentation for preparing patches without it is not especially
relevant anymore and may serve to confuse new contributors.

Signed-off-by: Drew DeVault <sir@cmpwn.com>
---
Conflict of interest: I wrote and maintain the website,
git-send-email.io, which is recommended in the revised document.

 Documentation/process/submitting-patches.rst | 91 +++++---------------
 1 file changed, 22 insertions(+), 69 deletions(-)

diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index dd008b89bca5..4e93e682e7ac 100644
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -18,11 +18,10 @@ submitting code.  If you are submitting a driver, also read
 for device tree binding patches, read
 Documentation/devicetree/bindings/submitting-patches.rst.
 
-Many of these steps describe the default behavior of the ``git`` version
-control system; if you use ``git`` to prepare your patches, you'll find much
-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.
+This documentation assumes that you're using ``git`` to prepare your patches.
+If you're unfamiliar with ``git``, you would be well-advised to learn how to
+use it, it will make your life as a kernel developer and in general much
+easier.
 
 Obtain a current source tree
 -------------------------------
@@ -39,64 +38,6 @@ patches prepared against those trees.  See the **T:** entry for the subsystem
 in the MAINTAINERS file to find that tree, or simply ask the maintainer if
 the tree is not listed there.
 
-It is still possible to download kernel releases via tarballs (as described
-in the next section), but that is the hard way to do kernel development.
-
-1) ``diff -up``
----------------
-
-If you must generate your patches by hand, use ``diff -up`` or ``diff -uprN``
-to create patches.  Git generates patches in this form by default; if
-you're using ``git``, you can skip this section entirely.
-
-All changes to the Linux kernel occur in the form of patches, as
-generated by :manpage:`diff(1)`.  When creating your patch, make sure to
-create it in "unified diff" format, as supplied by the ``-u`` argument
-to :manpage:`diff(1)`.
-Also, please use the ``-p`` argument which shows which C function each
-change is in - that makes the resultant ``diff`` a lot easier to read.
-Patches should be based in the root kernel source directory,
-not in any lower subdirectory.
-
-To create a patch for a single file, it is often sufficient to do::
-
-	SRCTREE=linux
-	MYFILE=drivers/net/mydriver.c
-
-	cd $SRCTREE
-	cp $MYFILE $MYFILE.orig
-	vi $MYFILE	# make your change
-	cd ..
-	diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch
-
-To create a patch for multiple files, you should unpack a "vanilla",
-or unmodified kernel source tree, and generate a ``diff`` against your
-own source tree.  For example::
-
-	MYSRC=/devel/linux
-
-	tar xvfz linux-3.19.tar.gz
-	mv linux-3.19 linux-3.19-vanilla
-	diff -uprN -X linux-3.19-vanilla/Documentation/dontdiff \
-		linux-3.19-vanilla $MYSRC > /tmp/patch
-
-``dontdiff`` is a list of files which are generated by the kernel during
-the build process, and should be ignored in any :manpage:`diff(1)`-generated
-patch.
-
-Make sure your patch does not include any extra files which do not
-belong in a patch submission.  Make sure to review your patch -after-
-generating it with :manpage:`diff(1)`, to ensure accuracy.
-
-If your changes produce a lot of deltas, you need to split them into
-individual patches which modify things in logical stages; see
-:ref:`split_changes`.  This will facilitate review by other kernel developers,
-very important if you want your patch accepted.
-
-If you're using ``git``, ``git rebase -i`` can help you with this process.  If
-you're not using ``git``, ``quilt`` <https://savannah.nongnu.org/projects/quilt>
-is another popular alternative.
-
 .. _describe_changes:
 
 Describe your changes
@@ -350,7 +291,12 @@ on the changes you are submitting.  It is important for a kernel
 developer to be able to "quote" your changes, using standard e-mail
 tools, so that they may comment on specific portions of your code.
 
-For this reason, all patches should be submitted by e-mail "inline".
+For this reason, all patches should be submitted by e-mail "inline". The
+easiest way to do this is with ``git send-email``, which is strongly
+recommended.  An interactive tutorial for ``git send-email`` is available at
+https://git-send-email.io.
+
+If you choose not to use ``git send-email``:
 
 .. warning::
 
@@ -380,13 +326,17 @@ server, and provide instead a URL (link) pointing to your patch.  But note
 that if your patch exceeds 300 kB, it almost certainly needs to be broken up
 anyway.
 
-8) Respond to review comments
+``git request-pull`` may be used to generate an email which summarizes your changes
+and provides a URL to fetch your tree from. See :ref:`_request_pull`.
+
+Respond to review comments
 -----------------------------
 
 Your patch will almost certainly get comments from reviewers on ways in
-which the patch can be improved.  You must respond to those comments;
-ignoring reviewers is a good way to get ignored in return.  Review comments
-or questions that do not lead to a code change should almost certainly
+which the patch can be improved, in the form of a reply to your email. You must
+respond to those comments; ignoring reviewers is a good way to get ignored in
+return. You can simply reply to their emails to answer their comments. Review
+comments or questions that do not lead to a code change should almost certainly
 bring about a comment or changelog entry so that the next reviewer better
 understands what is going on.
 
@@ -421,6 +371,7 @@ convention to prefix your subject line with [PATCH].  This lets Linus
 and other kernel developers more easily distinguish patches from other
 e-mail discussions.
 
+``git send-email`` will do this for you automatically.
 
 
 Sign your work - the Developer's Certificate of Origin
@@ -468,13 +419,14 @@ then you just add a line saying::
 	Signed-off-by: Random J Developer <random@developer.example.org>
 
 using your real name (sorry, no pseudonyms or anonymous contributions.)
+This will be done for you automatically if you use ``git commit -s``.
 
 Some people also put extra tags at the end.  They'll just be ignored for
 now, but you can do this to mark internal company procedures or just
 point out some special detail about the sign-off.
 
 
-12) When to use Acked-by:, Cc:, and Co-developed-by:
+When to use Acked-by:, Cc:, and Co-developed-by:
 -------------------------------------------------------
 
 The Signed-off-by: tag indicates that the signer was involved in the
@@ -794,6 +746,7 @@ letter or in the first patch of the series and it should be placed
 either below the ``---`` line or at the very bottom of all other
 content, right before your email signature.
 
+.. _request_pull:
 
 Sending ``git pull`` requests
 ---------------------------------
-- 
2.28.0

Re: [PATCH 4/4] submitting-patches.rst: presume git will be used

[Randy Dunlap]

On 9/2/20 8:57 AM, Drew DeVault wrote:
> Git is fairly ubiquitous these days, and the additional information in
> this documentation for preparing patches without it is not especially
> relevant anymore and may serve to confuse new contributors.
> 
> Signed-off-by: Drew DeVault <sir@cmpwn.com>
> ---
> Conflict of interest: I wrote and maintain the website,
> git-send-email.io, which is recommended in the revised document.

Understood. And how long do you expect to actively maintain those 2 websites?

At least ask archive.org to make backup/copies of them periodically...

>  Documentation/process/submitting-patches.rst | 91 +++++---------------
>  1 file changed, 22 insertions(+), 69 deletions(-)


thanks.
-- 
~Randy

Re: [PATCH 4/4] submitting-patches.rst: presume git will be used

[Drew DeVault]

On Wed Sep 2, 2020 at 12:11 PM EDT, Randy Dunlap wrote:
> On 9/2/20 8:57 AM, Drew DeVault wrote:
> > Git is fairly ubiquitous these days, and the additional information in
> > this documentation for preparing patches without it is not especially
> > relevant anymore and may serve to confuse new contributors.
> > 
> > Signed-off-by: Drew DeVault <sir@cmpwn.com>
> > ---
> > Conflict of interest: I wrote and maintain the website,
> > git-send-email.io, which is recommended in the revised document.
>
> Understood. And how long do you expect to actively maintain those 2
> websites?

Perpetually. I am financially incentivized to on behalf of sourcehut.
It's also open source:

https://git.sr.ht/~sircmpwn/git-send-email.io

And the wayback machine has already picked it up:

https://web.archive.org/web/*/https://git-send-email.io

Though that won't help if the interactive backend bit goes away.

Re: [PATCH 4/4] submitting-patches.rst: presume git will be used

[Jonathan Corbet]

On Wed,  2 Sep 2020 11:57:59 -0400
Drew DeVault <sir@cmpwn.com> wrote:

> Git is fairly ubiquitous these days, and the additional information in
> this documentation for preparing patches without it is not especially
> relevant anymore and may serve to confuse new contributors.
> 
> Signed-off-by: Drew DeVault <sir@cmpwn.com>

This is generally good, but I have a comment (of course!)...

[...]

> @@ -380,13 +326,17 @@ server, and provide instead a URL (link) pointing to your patch.  But note
>  that if your patch exceeds 300 kB, it almost certainly needs to be broken up
>  anyway.
>  
> -8) Respond to review comments
> +``git request-pull`` may be used to generate an email which summarizes your changes
> +and provides a URL to fetch your tree from. See :ref:`_request_pull`.

I'm not sure we want to be suggesting pull requests in our basic document
on patch submission.  Few, if any, maintainers will pull from developers
who still need this document.

Actually, I think this whole section ("E-mail size") is wrong, now that I
look at it.  People who post patches behind a URL rarely get a favorable
response.  Maybe we should just delete that section entirely?

Thanks,

jon