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