[PATCH] docs: submitting-patches: Require base tree information

[Eric Biggers <ebiggers@kernel.org>]

Many patches still don't include base tree information and can't be
applied.  Such patches can't be properly reviewed or tested, nor can
they be accepted.  submitting-patches.rst already describes how to
include base tree information, but it's characterized as optional,
appears only towards the end of the document, and is missing details.

Make some tweaks to hopefully increase the number of patches that
include base tree information:

- Characterize base tree information as required, not optional.

- Mention it in the "The canonical patch format" section too.

- Clarify what commits are acceptable to use as base commits.  Also use
  origin/master instead of master in the example.

- Mention how to handle prerequisite patches.

- Suggest setting the format.useAutoBase=true git configuration option.

- Mention falling back to free-form text as a last resort.

- Don't say base-commit can go "below the '---' line", since that
  implied it could go before the diff, which is an unnecessary
  alternative that differs from what 'git format-patch' produces.

- Free up some space for the new information by dropping the mention of
  needing at least git v2.9.0 (since that's quite old by now) and the
  example of 'git am' (since that isn't directly relevant to submitting
  patches, which is the topic of submitting-patches.rst).

Signed-off-by: Eric Biggers <ebiggers@kernel.org>
---
 Documentation/process/submitting-patches.rst | 92 ++++++++++++--------
 1 file changed, 58 insertions(+), 34 deletions(-)

diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index 7ae79452e1b46..ef211c9a63794 100644
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -25,6 +25,8 @@ Some subsystems and maintainer trees have additional information about
 their workflow and expectations, see
 Documentation/process/maintainer-handbooks.rst.
 
+.. _obtain_a_current_source_tree:
+
 Obtain a current source tree
 ----------------------------
 
@@ -678,6 +680,10 @@ The canonical patch message body contains the following:
 
   - The actual patch (``diff`` output).
 
+  - A ``base-commit`` line and zero or more ``prerequisite-patch-id``
+    lines. (For a series, these are needed only in the cover letter or
+    first patch.) See :ref:`providing_base_tree_information`.
+
 The Subject line format makes it very easy to sort the emails
 alphabetically by subject line - pretty much any email reader will
 support that - since because the sequence number is zero-padded,
@@ -847,6 +853,7 @@ unmanageable forest of references in email clients.  If a link is
 helpful, you can use the https://lore.kernel.org/ redirector (e.g., in
 the cover email text) to link to an earlier version of the patch series.
 
+.. _providing_base_tree_information:
 
 Providing base tree information
 -------------------------------
@@ -861,50 +868,67 @@ This is even more important for automated CI processes that attempt to
 run a series of tests in order to establish the quality of your
 submission before the maintainer starts the review.
 
-If you are using ``git format-patch`` to generate your patches, you can
-automatically include the base tree information in your submission by
-using the ``--base`` flag. The easiest and most convenient way to use
-this option is with topical branches::
+Therefore, with only rare exceptions, patches must include structured
+base tree information in the form of a
+``base-commit: <full commit hash>`` line naming a public commit, and
+zero or more ``prerequisite-patch-id: <patch-id>`` lines. They go in
+the first patch, or in the cover letter if one is present. Put them at
+the very bottom, after the diff (or, in a cover letter, after the
+diffstat) and just before the ``--`` signature delimiter if present.
+
+To make ``git format-patch`` generate this information, pass ``--base``.
+It's easiest to use topical branches and ``--base=auto``::
 
-    $ git checkout -t -b my-topical-branch master
-    Branch 'my-topical-branch' set up to track local branch 'master'.
+    $ git checkout -t -b my-topical-branch origin/master
+    branch 'my-topical-branch' set up to track 'origin/master'.
     Switched to a new branch 'my-topical-branch'
 
     [perform your edits and commits]
 
-    $ git format-patch --base=auto --cover-letter -o outgoing/ master
-    outgoing/0000-cover-letter.patch
-    outgoing/0001-First-Commit.patch
-    outgoing/...
+    $ git format-patch --base=auto --cover-letter origin/master
+    0000-cover-letter.patch
+    0001-First-Commit.patch
+    ...
 
-When you open ``outgoing/0000-cover-letter.patch`` for editing, you will
-notice that it will have the ``base-commit:`` trailer at the very
-bottom, which provides the reviewer and the CI tools enough information
-to properly perform ``git am`` without worrying about conflicts::
+For more information about ``--base``, see ``man git-format-patch``.
 
-    $ git checkout -b patch-review [base-commit-id]
-    Switched to a new branch 'patch-review'
-    $ git am patches.mbox
-    Applying: First Commit
-    Applying: ...
-
-Please see ``man git-format-patch`` for more information about this
-option.
+To ensure you don't forget to use ``--base``, consider setting the
+``format.useAutoBase=true`` git configuration option to make
+``git format-patch`` default to ``--base=auto``.
 
 .. note::
 
-    The ``--base`` feature was introduced in git version 2.9.0.
-
-If you are not using git to format your patches, you can still include
-the same ``base-commit`` trailer to indicate the commit hash of the tree
-on which your work is based. You should add it either in the cover
-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.
-
-Make sure that base commit is in an official maintainer/mainline tree
-and not in some internal, accessible only to you tree - otherwise it
-would be worthless.
+    If ``git format-patch`` with ``--base=auto`` (or
+    ``format.useAutoBase=true``) can't detect a base commit, e.g. due to
+    the current branch having no upstream tracking branch, it exits with
+    an error. In such cases, pass an explicit base commit to ``--base``
+    instead. This is also needed if git detects the wrong base commit,
+    such as when the upstream branch has local, unpublished commits.
+
+The base commit must be in a well-known public tree, such as the
+subsystem development branch the patch is targeting. See
+:ref:`obtain_a_current_source_tree`. Mainline or the latest linux-next
+can also be acceptable bases, depending on the subsystem.
+
+If your patch(es) depend on unmerged patches that were sent separately,
+then use the same base commit as those prerequisite patches. In your
+local git branch, apply the prerequisite patches directly on top of the
+desired base commit, then commit your new changes on top of that. Then,
+run a command like the following::
+
+    $ git format-patch --base=<base> --cover-letter <last-prereq>..HEAD
+
+That makes ``git format-patch`` generate a ``base-commit`` line as well
+as ``prerequisite-patch-id`` lines for the dependencies.
+
+In rare cases where the structured base tree information isn't flexible
+enough (such as when prerequisite patches weren't sent publicly, were
+modified from what was sent publicly, or weren't sent with the default 3
+lines of context that git uses to compute patch IDs), as a last resort
+use free-form text in the cover letter or below the ``---`` line to
+describe how to apply your patch(es). Giving a link to your patches in a
+publicly accessible git branch can help in this case. However, note that
+CI systems may be unable to apply your patch(es).
 
 Tooling
 -------

base-commit: f47d223627f80cb7a1eb14c585fe6cb35de5e984
-- 
2.56.0.212.g129ede20d9-goog