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@xxxxxxx>
> Link: https://lore.kernel.org/all/arSMwd1bGO1vrif-@xxxxxxx/
> Signed-off-by: Matthias Goergens <matthias.goergens@xxxxxxxxx>

Reviewed-by: Eric Biggers <ebiggers@xxxxxxxxxx>

>  	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