[PATCH v2] MAINTAINERS: document the branch in git T: entries

[PATCH v2] MAINTAINERS: document the branch in git T: entries

[Matthias Goergens]

A git T: entry can name a branch after the repository URL.  The first
to do so, commit a1aa5a770dc3 ("MAINTAINERS: update hwmon subsystem
git trees"), added two T: lines for one repository, one per branch.
Today 109 of the 846 git T: lines name a branch, and ten entries list
one repository more than once with different branches.  Commit
083bf9c56d06 ("get_maintainer: add more --self-test options") taught
get_maintainer.pl to check the branch with git ls-remote.  Neither the
MAINTAINERS preamble nor submitting-patches.rst mentions any of this.

Document the syntax only.  What a named branch is for varies: many
entries name the branch linux-next merges, others a fixes or topic
branch, and some subsystems want patches based on a mainline tag rather
than on any branch of their tree.  maintainer-entry-profile.rst already
asks a profile to say which branches go into linux-next and which one
contributors should submit against, so point there.

In submitting-patches.rst, say that fixes for the current release cycle
and new development usually start from different places, and where to
find out which.

Suggested-by: Theodore Ts'o <tytso@mit.edu>
Link: https://lore.kernel.org/all/arSMwd1bGO1vrif-@mit.edu/
Signed-off-by: Matthias Goergens <matthias.goergens@gmail.com>
---
v2:
- Krzysztof: one patch instead of two.  The header no longer says when
  to name a branch (v1 tied that to the repository's HEAD); it
  documents the syntax only.  submitting-patches.rst names the branch
  that queues work for linux-next as the usual base for new
  development.  The cgit about page he mentions is a good place to
  describe branches, but not every tree has one, so the text does not
  point there.
- Marc: some trees are integration-only and want patches on a mainline
  tag, so what to base patches on is left to the P: profile or the
  maintainer:
  https://lore.kernel.org/all/875wzu4vuv.wl-maz@kernel.org/
- Niklas: fixes for the current release cycle are now told apart from
  new development.  memblock is not alone: ten entries list one
  repository with several branches, so the header says an entry may do
  that, without recommending it over a single line.
- Eric: his fsverity patch uses one T: line per branch, which the text
  allows:
  https://lore.kernel.org/all/20260925041654.112935-1-ebiggers@kernel.org/
  Pointing HEAD at the main branch with gitolite's symbolic-ref, as he
  suggested, is up to each maintainer and is not covered here:
  https://lore.kernel.org/all/20260924040030.GB5048@sol/
- Ted: documenting the branch at all was his suggestion (Link: above).

v1: https://lore.kernel.org/all/64b0be79c535bb9545f9f81a5044146a8726c761.1790220653.git.matthias.goergens@gmail.com/

 Documentation/process/submitting-patches.rst | 8 ++++++++
 MAINTAINERS                                  | 5 +++++
 2 files changed, 13 insertions(+)

diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index 7ae79452e1b4..cfc72975a9d6 100644
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -40,6 +40,14 @@ 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.
 
+What to base a patch on also depends on what it is.  A fix that should reach
+mainline during the current release cycle, such as a regression fix, is
+usually based on the latest mainline or on the subsystem's fixes branch.  New
+development is usually based on the branch where the subsystem queues work for
+the next merge window, which linux-next merges and which the **T:** entry may
+name.  When in doubt, check the subsystem's **P:** profile, if there is one,
+or ask the maintainer.
+
 .. _describe_changes:
 
 Describe your changes
diff --git a/MAINTAINERS b/MAINTAINERS
index c52ec2d7d3c1..c3f8fc52f3ec 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -30,6 +30,11 @@ Descriptions of section entries and preferred order
        See Documentation/maintainer/maintainer-entry-profile.rst for details.
 	T: *SCM* tree type and location.
 	   Type is one of: git, hg, quilt, stgit, topgit
+	   A git entry may name a branch after the URL, and an entry may
+	   have several T: lines, for example one per branch.  What each
+	   branch is for, and what to base patches on, differs between
+	   subsystems: see the P: profile, if there is one, or ask the
+	   maintainer.
 	F: *Files* and directories wildcard patterns.
 	   A trailing slash includes all files and subdirectory files.
 	   F:	drivers/net/	all files in and below drivers/net

base-commit: 165768bb70265b5c38cf0b73fafd75be235f8b14
-- 
2.55.0

Re: [PATCH v2] MAINTAINERS: document the branch in git T: entries

[Niklas Cassel]

On Fri, Sep 25, 2026 at 08:00:47PM +0800, Matthias Goergens wrote:
> A git T: entry can name a branch after the repository URL.  The first
> to do so, commit a1aa5a770dc3 ("MAINTAINERS: update hwmon subsystem
> git trees"), added two T: lines for one repository, one per branch.
> Today 109 of the 846 git T: lines name a branch, and ten entries list
> one repository more than once with different branches.  Commit
> 083bf9c56d06 ("get_maintainer: add more --self-test options") taught
> get_maintainer.pl to check the branch with git ls-remote.  Neither the
> MAINTAINERS preamble nor submitting-patches.rst mentions any of this.
> 
> Document the syntax only.  What a named branch is for varies: many
> entries name the branch linux-next merges, others a fixes or topic
> branch, and some subsystems want patches based on a mainline tag rather
> than on any branch of their tree.  maintainer-entry-profile.rst already
> asks a profile to say which branches go into linux-next and which one
> contributors should submit against, so point there.
> 
> In submitting-patches.rst, say that fixes for the current release cycle
> and new development usually start from different places, and where to
> find out which.
> 
> Suggested-by: Theodore Ts'o <tytso@mit.edu>
> Link: https://lore.kernel.org/all/arSMwd1bGO1vrif-@mit.edu/
> Signed-off-by: Matthias Goergens <matthias.goergens@gmail.com>
> ---
> v2:
> - Krzysztof: one patch instead of two.  The header no longer says when
>   to name a branch (v1 tied that to the repository's HEAD); it
>   documents the syntax only.  submitting-patches.rst names the branch
>   that queues work for linux-next as the usual base for new
>   development.  The cgit about page he mentions is a good place to
>   describe branches, but not every tree has one, so the text does not
>   point there.
> - Marc: some trees are integration-only and want patches on a mainline
>   tag, so what to base patches on is left to the P: profile or the
>   maintainer:
>   https://lore.kernel.org/all/875wzu4vuv.wl-maz@kernel.org/
> - Niklas: fixes for the current release cycle are now told apart from
>   new development.  memblock is not alone: ten entries list one
>   repository with several branches, so the header says an entry may do
>   that, without recommending it over a single line.
> - Eric: his fsverity patch uses one T: line per branch, which the text
>   allows:
>   https://lore.kernel.org/all/20260925041654.112935-1-ebiggers@kernel.org/
>   Pointing HEAD at the main branch with gitolite's symbolic-ref, as he
>   suggested, is up to each maintainer and is not covered here:
>   https://lore.kernel.org/all/20260924040030.GB5048@sol/
> - Ted: documenting the branch at all was his suggestion (Link: above).
> 
> v1: https://lore.kernel.org/all/64b0be79c535bb9545f9f81a5044146a8726c761.1790220653.git.matthias.goergens@gmail.com/
> 
>  Documentation/process/submitting-patches.rst | 8 ++++++++
>  MAINTAINERS                                  | 5 +++++
>  2 files changed, 13 insertions(+)
> 
> diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
> index 7ae79452e1b4..cfc72975a9d6 100644
> --- a/Documentation/process/submitting-patches.rst
> +++ b/Documentation/process/submitting-patches.rst
> @@ -40,6 +40,14 @@ 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.
>  
> +What to base a patch on also depends on what it is.  A fix that should reach
> +mainline during the current release cycle, such as a regression fix, is
> +usually based on the latest mainline or on the subsystem's fixes branch.  New
> +development is usually based on the branch where the subsystem queues work for
> +the next merge window, which linux-next merges and which the **T:** entry may
> +name.  When in doubt, check the subsystem's **P:** profile, if there is one,
> +or ask the maintainer.
> +
>  .. _describe_changes:
>  
>  Describe your changes
> diff --git a/MAINTAINERS b/MAINTAINERS
> index c52ec2d7d3c1..c3f8fc52f3ec 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -30,6 +30,11 @@ Descriptions of section entries and preferred order
>         See Documentation/maintainer/maintainer-entry-profile.rst for details.
>  	T: *SCM* tree type and location.
>  	   Type is one of: git, hg, quilt, stgit, topgit
> +	   A git entry may name a branch after the URL, and an entry may
> +	   have several T: lines, for example one per branch.  What each
> +	   branch is for, and what to base patches on, differs between
> +	   subsystems: see the P: profile, if there is one, or ask the
> +	   maintainer.
>  	F: *Files* and directories wildcard patterns.
>  	   A trailing slash includes all files and subdirectory files.
>  	   F:	drivers/net/	all files in and below drivers/net
> 
> base-commit: 165768bb70265b5c38cf0b73fafd75be235f8b14
> -- 
> 2.55.0
> 

Looks like a good change to me:

Reviewed-by: Niklas Cassel <cassel@kernel.org>

Re: [PATCH v2] MAINTAINERS: document the branch in git T: entries

[Krzysztof Kozlowski]

On 25/09/2026 14:00, Matthias Goergens wrote:
> A git T: entry can name a branch after the repository URL.  The first
> to do so, commit a1aa5a770dc3 ("MAINTAINERS: update hwmon subsystem
> git trees"), added two T: lines for one repository, one per branch.
> Today 109 of the 846 git T: lines name a branch, and ten entries list
> one repository more than once with different branches.  Commit
> 083bf9c56d06 ("get_maintainer: add more --self-test options") taught
> get_maintainer.pl to check the branch with git ls-remote.  Neither the
> MAINTAINERS preamble nor submitting-patches.rst mentions any of this.
> 
> Document the syntax only.  What a named branch is for varies: many
> entries name the branch linux-next merges, others a fixes or topic
> branch, and some subsystems want patches based on a mainline tag rather
> than on any branch of their tree.  maintainer-entry-profile.rst already
> asks a profile to say which branches go into linux-next and which one
> contributors should submit against, so point there.
> 
> In submitting-patches.rst, say that fixes for the current release cycle
> and new development usually start from different places, and where to
> find out which.
> 
> Suggested-by: Theodore Ts'o <tytso@mit.edu>
> Link: https://lore.kernel.org/all/arSMwd1bGO1vrif-@mit.edu/
> Signed-off-by: Matthias Goergens <matthias.goergens@gmail.com>

Reviewed-by: Krzysztof Kozlowski <krzysztof.kozlowski@oss.qualcomm.com>

Best regards,
Krzysztof

Re: [PATCH v2] MAINTAINERS: document the branch in git T: entries

[Marc Zyngier]

On Fri, 25 Sep 2026 13:00:47 +0100,
Matthias Goergens <matthias.goergens@gmail.com> wrote:
> 
> A git T: entry can name a branch after the repository URL.  The first
> to do so, commit a1aa5a770dc3 ("MAINTAINERS: update hwmon subsystem
> git trees"), added two T: lines for one repository, one per branch.
> Today 109 of the 846 git T: lines name a branch, and ten entries list
> one repository more than once with different branches.  Commit
> 083bf9c56d06 ("get_maintainer: add more --self-test options") taught
> get_maintainer.pl to check the branch with git ls-remote.  Neither the
> MAINTAINERS preamble nor submitting-patches.rst mentions any of this.
> 
> Document the syntax only.  What a named branch is for varies: many
> entries name the branch linux-next merges, others a fixes or topic
> branch, and some subsystems want patches based on a mainline tag rather
> than on any branch of their tree.  maintainer-entry-profile.rst already
> asks a profile to say which branches go into linux-next and which one
> contributors should submit against, so point there.
> 
> In submitting-patches.rst, say that fixes for the current release cycle
> and new development usually start from different places, and where to
> find out which.
> 
> Suggested-by: Theodore Ts'o <tytso@mit.edu>
> Link: https://lore.kernel.org/all/arSMwd1bGO1vrif-@mit.edu/
> Signed-off-by: Matthias Goergens <matthias.goergens@gmail.com>

Acked-by: Marc Zyngier <maz@kernel.org>

	M.

-- 
Jazz isn't dead. It just smells funny.

Re: [PATCH v2] MAINTAINERS: document the branch in git T: entries

[Eric Biggers]

On Fri, Sep 25, 2026 at 08:00:47PM +0800, Matthias Goergens wrote:
> A git T: entry can name a branch after the repository URL.  The first
> to do so, commit a1aa5a770dc3 ("MAINTAINERS: update hwmon subsystem
> git trees"), added two T: lines for one repository, one per branch.
> Today 109 of the 846 git T: lines name a branch, and ten entries list
> one repository more than once with different branches.  Commit
> 083bf9c56d06 ("get_maintainer: add more --self-test options") taught
> get_maintainer.pl to check the branch with git ls-remote.  Neither the
> MAINTAINERS preamble nor submitting-patches.rst mentions any of this.
> 
> Document the syntax only.  What a named branch is for varies: many
> entries name the branch linux-next merges, others a fixes or topic
> branch, and some subsystems want patches based on a mainline tag rather
> than on any branch of their tree.  maintainer-entry-profile.rst already
> asks a profile to say which branches go into linux-next and which one
> contributors should submit against, so point there.
> 
> In submitting-patches.rst, say that fixes for the current release cycle
> and new development usually start from different places, and where to
> find out which.
> 
> Suggested-by: Theodore Ts'o <tytso@mit.edu>
> Link: https://lore.kernel.org/all/arSMwd1bGO1vrif-@mit.edu/
> Signed-off-by: Matthias Goergens <matthias.goergens@gmail.com>

Reviewed-by: Eric Biggers <ebiggers@kernel.org>

>  	T: *SCM* tree type and location.
>  	   Type is one of: git, hg, quilt, stgit, topgit
> +	   A git entry may name a branch after the URL, and an entry may
> +	   have several T: lines, for example one per branch.  What each
> +	   branch is for, and what to base patches on, differs between
> +	   subsystems: see the P: profile, if there is one, or ask the
> +	   maintainer.

I would hope that the convention of one branch for the next release and
one branch for the current release is common enough that it could be
documented as the usual convention here.  But maybe there are too many
odd subsystems that do something different.

- Eric