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

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

[Eric Biggers]

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

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

[Konstantin Ryabitsev]

On Tue, Oct 20, 2026 at 09:22:35PM +0000, Eric Biggers wrote:
> 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.

I'm happy with this change, but I'd disambiguate the title a bit. With b4, we
started providing both a base-commit and base-tree footer, specifically
because often times the "base-commit:" line by itself is not sufficient.

Imagine this scenario: a developer is working on some code in a feature branch
and come across a pre-existing bug. They create a fork off of their feature
branch to fix the bug and send it in. In this situation, the "base-commit"
footer would be meaningless, because it references some transient commit-id in
their feature branch. In an ideal scenario, the developer would rebase that
bugfix branch on a known tag, but that doesn't always happen.

This observation doesn't really preclude this patch from being accepted, I'm
just recording my own experience that, by itself, base-commit is often
insufficient.

Reviewed-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>

-K

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

[Weijie Yuan]

Eric Biggers <ebiggers@kernel.org> writes:

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

LGTM!

Reviewed-by: Weijie Yuan <wy@wyuan.org>

Thanks.

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

[Randy Dunlap]

On 10/20/26 3:07 PM, Konstantin Ryabitsev wrote:
> On Tue, Oct 20, 2026 at 09:22:35PM +0000, Eric Biggers wrote:
>> 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.
> 
> I'm happy with this change, but I'd disambiguate the title a bit. With b4, we
> started providing both a base-commit and base-tree footer, specifically
> because often times the "base-commit:" line by itself is not sufficient.
> 
> Imagine this scenario: a developer is working on some code in a feature branch
> and come across a pre-existing bug. They create a fork off of their feature
> branch to fix the bug and send it in. In this situation, the "base-commit"
> footer would be meaningless, because it references some transient commit-id in
> their feature branch. In an ideal scenario, the developer would rebase that
> bugfix branch on a known tag, but that doesn't always happen.
> 
> This observation doesn't really preclude this patch from being accepted, I'm
> just recording my own experience that, by itself, base-commit is often
> insufficient.

Yeah, I was wondering about specifying tree as well as commit, so thanks
answering before I even asked the question.

Most of my patches are made against linux-next.  So: is this going to be
acceptable?

(for linux-next-20261020:)
base-commit: 053966c344dbd346e71305f530e91ea77916189f
base-tree: git://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git master

linux-next how has over 400 trees in it. That's a tad prohibitive AFA cloning is
concerned.


thanks.
-- 
~Randy

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

[Krzysztof Kozlowski]

On 20/10/2026 23:22, Eric Biggers wrote:
> -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.

I disagree, that's pointlessly too hard requirement.

For many of my contributions base is obvious and not needed to be
explicitly defined. For all the patches I accept, answer is the same -
base is either obvious or if not and patch does not apply, then the base
does not matter.

Requiring it is just bureaucracy without actual benefit.

The only benefit would be if maintainer COULD change its base to apply
some patch with odd base... but this cannot happen. Maintainer base is
fixed - it's the HEAD of his development branch for given category of
commits (e.g. DTS branch for SoC maintainers).

Best regards,
Krzysztof

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

[Krzysztof Kozlowski]

On 21/10/2026 08:07, Randy Dunlap wrote:
> 
> 
> On 10/20/26 3:07 PM, Konstantin Ryabitsev wrote:
>> On Tue, Oct 20, 2026 at 09:22:35PM +0000, Eric Biggers wrote:
>>> 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.
>>
>> I'm happy with this change, but I'd disambiguate the title a bit. With b4, we
>> started providing both a base-commit and base-tree footer, specifically
>> because often times the "base-commit:" line by itself is not sufficient.
>>
>> Imagine this scenario: a developer is working on some code in a feature branch
>> and come across a pre-existing bug. They create a fork off of their feature
>> branch to fix the bug and send it in. In this situation, the "base-commit"
>> footer would be meaningless, because it references some transient commit-id in
>> their feature branch. In an ideal scenario, the developer would rebase that
>> bugfix branch on a known tag, but that doesn't always happen.
>>
>> This observation doesn't really preclude this patch from being accepted, I'm
>> just recording my own experience that, by itself, base-commit is often
>> insufficient.
> 
> Yeah, I was wondering about specifying tree as well as commit, so thanks
> answering before I even asked the question.
> 
> Most of my patches are made against linux-next.  So: is this going to be
> acceptable?
> 
> (for linux-next-20261020:)
> base-commit: 053966c344dbd346e71305f530e91ea77916189f
> base-tree: git://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git master

According to commit msg which claims that without base information "nor
can they be accepted. " (ridiculous statement on its own, since base is
for these contributions obvious and known), next would not be
acceptable, because maintainers DO NOT work on next. So if base is
necessary for the patch "to be accepted", then base pointing to
something irrelevant to the maintainer does not fit that requirement.

This patch is just harmful to contribution process, just to fix
limitations of bots/testing tools which apparently do not understand we
have something like linux-next.

Nacked-by: Krzysztof Kozlowski <krzk@kernel.org>

Best regards,
Krzysztof

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

[Eric Biggers]

On Wed, Oct 21, 2026 at 08:26:28AM +0200, Krzysztof Kozlowski wrote:
> On 20/10/2026 23:22, Eric Biggers wrote:
> > -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.
> 
> I disagree, that's pointlessly too hard requirement.
> 
> For many of my contributions base is obvious and not needed to be
> explicitly defined. For all the patches I accept, answer is the same -
> base is either obvious or if not and patch does not apply, then the base
> does not matter.
> 
> Requiring it is just bureaucracy without actual benefit.
> 
> The only benefit would be if maintainer COULD change its base to apply
> some patch with odd base... but this cannot happen. Maintainer base is
> fixed - it's the HEAD of his development branch for given category of
> commits (e.g. DTS branch for SoC maintainers).

There are many use cases for applying patches besides the final patch
acceptance, such as review (by anyone, not just a maintainer), testing,
CI systems, etc.

HEAD of a branch is of course not fixed, and changes every time a patch
gets applied.  That's especially relevant when wanting to check out an
old patch for any reason.  Trying to guess a base commit based on the
date and patch subject is a waste of time.

- Eric

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

[Krzysztof Kozlowski]

On 21/10/2026 08:39, Eric Biggers wrote:
> On Wed, Oct 21, 2026 at 08:26:28AM +0200, Krzysztof Kozlowski wrote:
>> On 20/10/2026 23:22, Eric Biggers wrote:
>>> -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.
>>
>> I disagree, that's pointlessly too hard requirement.
>>
>> For many of my contributions base is obvious and not needed to be
>> explicitly defined. For all the patches I accept, answer is the same -
>> base is either obvious or if not and patch does not apply, then the base
>> does not matter.
>>
>> Requiring it is just bureaucracy without actual benefit.
>>
>> The only benefit would be if maintainer COULD change its base to apply
>> some patch with odd base... but this cannot happen. Maintainer base is
>> fixed - it's the HEAD of his development branch for given category of
>> commits (e.g. DTS branch for SoC maintainers).
> 
> There are many use cases for applying patches besides the final patch
> acceptance, such as review (by anyone, not just a maintainer), testing,
> CI systems, etc.
> 
> HEAD of a branch is of course not fixed, and changes every time a patch
> gets applied.  That's especially relevant when wanting to check out an
> old patch for any reason.  Trying to guess a base commit based on the
> date and patch subject is a waste of time.

All these tools should just work on top of linux-next. Requiring people
to add base like "next-20261021" or "tip-of-obvious-maintainer-tree" is
pointless. I understand that base is helping, but helping and requiring
an obvious information just do not go together.

So again: base has ZERO meaning to the maintainer process. It has
meaning to tools, so fix the tools to work on known and obvious trees.

Best regards,
Krzysztof

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

[Eric Biggers]

On Wed, Oct 21, 2026 at 08:35:04AM +0200, Krzysztof Kozlowski wrote:
> On 21/10/2026 08:07, Randy Dunlap wrote:
> > 
> > 
> > On 10/20/26 3:07 PM, Konstantin Ryabitsev wrote:
> >> On Tue, Oct 20, 2026 at 09:22:35PM +0000, Eric Biggers wrote:
> >>> 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.
> >>
> >> I'm happy with this change, but I'd disambiguate the title a bit. With b4, we
> >> started providing both a base-commit and base-tree footer, specifically
> >> because often times the "base-commit:" line by itself is not sufficient.
> >>
> >> Imagine this scenario: a developer is working on some code in a feature branch
> >> and come across a pre-existing bug. They create a fork off of their feature
> >> branch to fix the bug and send it in. In this situation, the "base-commit"
> >> footer would be meaningless, because it references some transient commit-id in
> >> their feature branch. In an ideal scenario, the developer would rebase that
> >> bugfix branch on a known tag, but that doesn't always happen.
> >>
> >> This observation doesn't really preclude this patch from being accepted, I'm
> >> just recording my own experience that, by itself, base-commit is often
> >> insufficient.
> > 
> > Yeah, I was wondering about specifying tree as well as commit, so thanks
> > answering before I even asked the question.
> > 
> > Most of my patches are made against linux-next.  So: is this going to be
> > acceptable?
> > 
> > (for linux-next-20261020:)
> > base-commit: 053966c344dbd346e71305f530e91ea77916189f
> > base-tree: git://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git master
> 
> According to commit msg which claims that without base information "nor
> can they be accepted. "

I actually wrote:

    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. 

So it's about patches that can't be applied due to lack of base tree
information (due to the obvious guess not working).  Not merely the lack
of such information by itself.

- Eric

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

[Krzysztof Kozlowski]

On 21/10/2026 08:44, Eric Biggers wrote:
>>> (for linux-next-20261020:)
>>> base-commit: 053966c344dbd346e71305f530e91ea77916189f
>>> base-tree: git://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git master
>>
>> According to commit msg which claims that without base information "nor
>> can they be accepted. "
> 
> I actually wrote:
> 
>     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. 
> 
> So it's about patches that can't be applied due to lack of base tree
> information (due to the obvious guess not working).  Not merely the lack
> of such information by itself.
> 

I have troubles in such case understanding that part of your commit msg.
I maintain a few different trees, accept patches there and send pull
requests to a few different upstream maintainers. I never had any
problem with applying a patch due to missing base. IOW, having there a
base tree information would not solve anything in "applied" or
"accepted" part.

Best regards,
Krzysztof

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

[Eric Biggers]

On Wed, Oct 21, 2026 at 08:41:47AM +0200, Krzysztof Kozlowski wrote:
> On 21/10/2026 08:39, Eric Biggers wrote:
> > On Wed, Oct 21, 2026 at 08:26:28AM +0200, Krzysztof Kozlowski wrote:
> >> On 20/10/2026 23:22, Eric Biggers wrote:
> >>> -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.
> >>
> >> I disagree, that's pointlessly too hard requirement.
> >>
> >> For many of my contributions base is obvious and not needed to be
> >> explicitly defined. For all the patches I accept, answer is the same -
> >> base is either obvious or if not and patch does not apply, then the base
> >> does not matter.
> >>
> >> Requiring it is just bureaucracy without actual benefit.
> >>
> >> The only benefit would be if maintainer COULD change its base to apply
> >> some patch with odd base... but this cannot happen. Maintainer base is
> >> fixed - it's the HEAD of his development branch for given category of
> >> commits (e.g. DTS branch for SoC maintainers).
> > 
> > There are many use cases for applying patches besides the final patch
> > acceptance, such as review (by anyone, not just a maintainer), testing,
> > CI systems, etc.
> > 
> > HEAD of a branch is of course not fixed, and changes every time a patch
> > gets applied.  That's especially relevant when wanting to check out an
> > old patch for any reason.  Trying to guess a base commit based on the
> > date and patch subject is a waste of time.
> 
> All these tools should just work on top of linux-next. Requiring people
> to add base like "next-20261021" or "tip-of-obvious-maintainer-tree" is
> pointless. I understand that base is helping, but helping and requiring
> an obvious information just do not go together.
> 
> So again: base has ZERO meaning to the maintainer process. It has
> meaning to tools, so fix the tools to work on known and obvious trees.

So what is your proposed algorithm to apply an arbitrary patch when
there's no base-commit?  Including any historical patch (from
months/years ago), patches with dependencies, etc.

- Eric

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

[Krzysztof Kozlowski]

On 21/10/2026 08:49, Eric Biggers wrote:
> On Wed, Oct 21, 2026 at 08:41:47AM +0200, Krzysztof Kozlowski wrote:
>> On 21/10/2026 08:39, Eric Biggers wrote:
>>> On Wed, Oct 21, 2026 at 08:26:28AM +0200, Krzysztof Kozlowski wrote:
>>>> On 20/10/2026 23:22, Eric Biggers wrote:
>>>>> -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.
>>>>
>>>> I disagree, that's pointlessly too hard requirement.
>>>>
>>>> For many of my contributions base is obvious and not needed to be
>>>> explicitly defined. For all the patches I accept, answer is the same -
>>>> base is either obvious or if not and patch does not apply, then the base
>>>> does not matter.
>>>>
>>>> Requiring it is just bureaucracy without actual benefit.
>>>>
>>>> The only benefit would be if maintainer COULD change its base to apply
>>>> some patch with odd base... but this cannot happen. Maintainer base is
>>>> fixed - it's the HEAD of his development branch for given category of
>>>> commits (e.g. DTS branch for SoC maintainers).
>>>
>>> There are many use cases for applying patches besides the final patch
>>> acceptance, such as review (by anyone, not just a maintainer), testing,
>>> CI systems, etc.
>>>
>>> HEAD of a branch is of course not fixed, and changes every time a patch
>>> gets applied.  That's especially relevant when wanting to check out an
>>> old patch for any reason.  Trying to guess a base commit based on the
>>> date and patch subject is a waste of time.
>>
>> All these tools should just work on top of linux-next. Requiring people
>> to add base like "next-20261021" or "tip-of-obvious-maintainer-tree" is
>> pointless. I understand that base is helping, but helping and requiring
>> an obvious information just do not go together.
>>
>> So again: base has ZERO meaning to the maintainer process. It has
>> meaning to tools, so fix the tools to work on known and obvious trees.
> 
> So what is your proposed algorithm to apply an arbitrary patch when

Already provided that, so to recap:

> there's no base-commit?  Including any historical patch (from
> months/years ago), patches with dependencies, etc.

Dependency is something else, but for every other patch:
1. For testing/CI: you apply on top of next
2. Every other case the maintainer knows where to apply it, because it
is his HEAD of next-branch.

I am repeating myself, but I really had no single problem of lack of
knowledge where to apply a patch as a maintainer or reviewer of some
subsystem, thus maybe I do not understand the actual problem you are
experiencing.

Best regards,
Krzysztof

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

[Jonathan Corbet]

Krzysztof Kozlowski <krzk@kernel.org> writes:

> For many of my contributions base is obvious and not needed to be
> explicitly defined. For all the patches I accept, answer is the same -
> base is either obvious or if not and patch does not apply, then the base
> does not matter.
>
> Requiring it is just bureaucracy without actual benefit.
>
> The only benefit would be if maintainer COULD change its base to apply
> some patch with odd base... but this cannot happen. Maintainer base is
> fixed - it's the HEAD of his development branch for given category of
> commits (e.g. DTS branch for SoC maintainers).

I fairly routinely get docs patches that don't apply to docs-next; when
I'm in the mood, I'll try to figure what they *do* apply to, then
cherry-pick them over.  Base information would make that process easier,
and even automatable.

Thanks,

jon

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

[Konstantin Ryabitsev]

On Wed, Oct 21, 2026 at 01:55:37PM +0200, Krzysztof Kozlowski wrote:
> >> So again: base has ZERO meaning to the maintainer process. It has
> >> meaning to tools, so fix the tools to work on known and obvious trees.
> > 
> > So what is your proposed algorithm to apply an arbitrary patch when
> 
> Already provided that, so to recap:
> 
> > there's no base-commit?  Including any historical patch (from
> > months/years ago), patches with dependencies, etc.
> 
> Dependency is something else, but for every other patch:
> 1. For testing/CI: you apply on top of next
> 2. Every other case the maintainer knows where to apply it, because it
> is his HEAD of next-branch.
> 
> I am repeating myself, but I really had no single problem of lack of
> knowledge where to apply a patch as a maintainer or reviewer of some
> subsystem, thus maybe I do not understand the actual problem you are
> experiencing.

From my perspective, I don't really want to force contributors to manually
provide the tree information, but it's helpful if tooling includes it
automatically.

Specifically, I am working on a service that eager-builds git bundles for all
submitted patch series -- the goal is to make it simple for CI systems to
fetch patch submissions as bundles that are already applicable against
mainline. Knowing which tree and commit the series is based on is really
helpful when figuring this out.

-K

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

[Krzysztof Kozlowski]

On 21/10/2026 17:04, Konstantin Ryabitsev wrote:
> On Wed, Oct 21, 2026 at 01:55:37PM +0200, Krzysztof Kozlowski wrote:
>> Dependency is something else, but for every other patch:
>> 1. For testing/CI: you apply on top of next
>> 2. Every other case the maintainer knows where to apply it, because it
>> is his HEAD of next-branch.
>>
>> I am repeating myself, but I really had no single problem of lack of
>> knowledge where to apply a patch as a maintainer or reviewer of some
>> subsystem, thus maybe I do not understand the actual problem you are
>> experiencing.
> 
> From my perspective, I don't really want to force contributors to manually
> provide the tree information, but it's helpful if tooling includes it
> automatically.

Sure, I do not oppose this being helpful. I oppose this being a
requirement and that was the impression I got from this patch.

> 
> Specifically, I am working on a service that eager-builds git bundles for all
> submitted patch series -- the goal is to make it simple for CI systems to
> fetch patch submissions as bundles that are already applicable against
> mainline. Knowing which tree and commit the series is based on is really
> helpful when figuring this out.

This has limitations you will not be able to solve. For example, around
SoC code (ARM, ARM64, RISC-V) are often combination of minimum two
subsystems:
1. Driver code + Devicetree bindings, being picked up by driver
maintainer, e.g. drivers/clock/ or drivers/reset/
2. DTS (arch/*/boot/dts) being picked up by SoC platform maintainer who
later sends it to SoC folks (Arnd Bergmann and folks).

Such patchsets by definition target independent trees, thus the only
reasonable base to fully test it or even apply it is the linux-next.
Contributors would not be able to provide base-commit different than
linux-next, thus that information is redundant - you can just assume it
is linux-next.

And if by "tree and commit the series is based on" you meant maintainer
tree, excluding linux-next, then that information could not be even
provided, unless patchset is split.

Best regards,
Krzysztof

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

[Krzysztof Kozlowski]

On 21/10/2026 16:19, Jonathan Corbet wrote:
> Krzysztof Kozlowski <krzk@kernel.org> writes:
> 
>> For many of my contributions base is obvious and not needed to be
>> explicitly defined. For all the patches I accept, answer is the same -
>> base is either obvious or if not and patch does not apply, then the base
>> does not matter.
>>
>> Requiring it is just bureaucracy without actual benefit.
>>
>> The only benefit would be if maintainer COULD change its base to apply
>> some patch with odd base... but this cannot happen. Maintainer base is
>> fixed - it's the HEAD of his development branch for given category of
>> commits (e.g. DTS branch for SoC maintainers).
> 
> I fairly routinely get docs patches that don't apply to docs-next; when
> I'm in the mood, I'll try to figure what they *do* apply to, then
> cherry-pick them over.  Base information would make that process easier,
> and even automatable.
> 

Some maintainers do that indeed and I propose not to. Every two months I
see one of my or other folks around my area patch which is being changed
in incorrect way between mailing list and Git. Change is done because:

1. Patch did not apply cleanly (a lot of simultaneous work, so base is
obviously old the moment the maintainer applies such patch)

2. Maintainer tried to resolve that by applying to the correct base (so
followed your process) and then did git rebase or cherry pick to his
final development branch.

3. Maintainer is overloaded and has no time to investigate whether
rebase/cherry-pick from above is truly correct, except building the
code, so every two months result of such rebase is wrong.

This is a real issue because it is very difficult to spot - your commit
is applied, but you never verify whether is applied THE SAME way and
maintainer thinks everything was applied cleanly.

If (1) happens and patch does not apply, the solution is to ask the
contributor to rebase.

So sorry, but the proper base rather encourages risky patch
merging/rebasing, instead of pushing the rebase problem to the person
actually knowing the patch and having hardware to validate it.

Best regards,
Krzysztof

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

[Laurent Pinchart]

On Wed, Oct 21, 2026 at 01:55:37PM +0200, Krzysztof Kozlowski wrote:
> On 21/10/2026 08:49, Eric Biggers wrote:
> > On Wed, Oct 21, 2026 at 08:41:47AM +0200, Krzysztof Kozlowski wrote:
> >> On 21/10/2026 08:39, Eric Biggers wrote:
> >>> On Wed, Oct 21, 2026 at 08:26:28AM +0200, Krzysztof Kozlowski wrote:
> >>>> On 20/10/2026 23:22, Eric Biggers wrote:
> >>>>> -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.
> >>>>
> >>>> I disagree, that's pointlessly too hard requirement.
> >>>>
> >>>> For many of my contributions base is obvious and not needed to be
> >>>> explicitly defined. For all the patches I accept, answer is the same -
> >>>> base is either obvious or if not and patch does not apply, then the base
> >>>> does not matter.
> >>>>
> >>>> Requiring it is just bureaucracy without actual benefit.
> >>>>
> >>>> The only benefit would be if maintainer COULD change its base to apply
> >>>> some patch with odd base... but this cannot happen. Maintainer base is
> >>>> fixed - it's the HEAD of his development branch for given category of
> >>>> commits (e.g. DTS branch for SoC maintainers).
> >>>
> >>> There are many use cases for applying patches besides the final patch
> >>> acceptance, such as review (by anyone, not just a maintainer), testing,
> >>> CI systems, etc.
> >>>
> >>> HEAD of a branch is of course not fixed, and changes every time a patch
> >>> gets applied.  That's especially relevant when wanting to check out an
> >>> old patch for any reason.  Trying to guess a base commit based on the
> >>> date and patch subject is a waste of time.
> >>
> >> All these tools should just work on top of linux-next. Requiring people
> >> to add base like "next-20261021" or "tip-of-obvious-maintainer-tree" is
> >> pointless. I understand that base is helping, but helping and requiring
> >> an obvious information just do not go together.
> >>
> >> So again: base has ZERO meaning to the maintainer process. It has
> >> meaning to tools, so fix the tools to work on known and obvious trees.
> > 
> > So what is your proposed algorithm to apply an arbitrary patch when
> 
> Already provided that, so to recap:
> 
> > there's no base-commit?  Including any historical patch (from
> > months/years ago), patches with dependencies, etc.
> 
> Dependency is something else, but for every other patch:
> 1. For testing/CI: you apply on top of next
> 2. Every other case the maintainer knows where to apply it, because it
> is his HEAD of next-branch.
> 
> I am repeating myself, but I really had no single problem of lack of
> knowledge where to apply a patch as a maintainer or reviewer of some
> subsystem, thus maybe I do not understand the actual problem you are
> experiencing.

When I review patches, I often need to apply them to a tree, mainly to
see the context, but sometimes also to test them. I have encountered
many cases where the patch wouldn't apply on the current for-next branch
of the relevant subsystem. That's often because the patch had
dependencies. When I'm lucky they are listed manually in the cover
letter with a link to a branch, but that's far from being the common
case. I then have to ask the submitter to provide a branch, or enough
information to recreate a branch. Having base information (base-commit,
prerequisite-patch-id, and possibly base-tree) would save me quite some
time.

I understand your concern about maintainers cherry-picking and sometimes
introducing issues as a result. In that case I also prefer asking the
submitter to rebase, retest, and resubmit. That's not what I want to use
base information for, in my case it helps with the review process.

-- 
Regards,

Laurent Pinchart

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

[Konstantin Ryabitsev]

On Wed, Oct 21, 2026 at 05:49:04PM +0200, Krzysztof Kozlowski wrote:
> > Specifically, I am working on a service that eager-builds git bundles for all
> > submitted patch series -- the goal is to make it simple for CI systems to
> > fetch patch submissions as bundles that are already applicable against
> > mainline. Knowing which tree and commit the series is based on is really
> > helpful when figuring this out.
> 
> This has limitations you will not be able to solve.

Oh, I am painfully aware of this -- but hopefully we'll hit most of the
standard cases. The upside of us doing it is that we have All The Objects (as
long as they have been pushed to our repos or the repos we mirror), so we
should be able to figure out the ancestry, hopefully. The base-tree info is
mostly useful for us to figure out the contributor's intent.

The service is still early in design stages and won't really be available for
a while yet -- but hopefully once it is, the other CI systems will be able to
benefit from us pre-solving the applicability so everyone doesn't have to do
it over and over on their own.

-K