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 <[email protected]>
Link: https://lore.kernel.org/all/[email protected]/
Signed-off-by: Matthias Goergens <[email protected]>
---
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/[email protected]/
- 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/[email protected]/
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.goerg...@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
