From: Linus Arver <linusa@xxxxxxxxxx>
The guidance to "base your work on the oldest branch that your change is
relevant to" was added in d0c26f0f56 (SubmittingPatches: Add new section
about what to base work on, 2010-04-19). That commit also added the
bullet points which describe the scenarios where one would use one of
"maint", "master", "next", and "seen" ("pu" in the original as that was
the name of this branch before it was renamed, per 828197de8f (docs:
adjust for the recent rename of `pu` to `seen`, 2020-06-25)).
The underlying principle of this guidance was probably something like
"base your work on the earlier-in-history branch so your change can be
merged forward". However, this principle is already concretely explained
in the accompanying bullet points. This principle should only come into
play if none of the scenarios described in the bullet points apply ---
and such a situation would be exceedingly rare.
Also, the guidance's wording of using the "oldest" branch is confusing
when read together with the rest of this section, because three of the
four named branches discussed ("master", "next", and "seen") move
frequently enough to not be considered "old" at all.
For these reasons, remove the guidance _without_ preserving the meaning
of the underlying principle, and instead add an overview of the four
named branches.
Helped-by: Jonathan Nieder <jrnieder@xxxxxxxxx>
Signed-off-by: Linus Arver <linusa@xxxxxxxxxx>
---
Documentation/SubmittingPatches | 11 +++++++++--
1 file changed, 9 insertions(+), 2 deletions(-)
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 48918181f49..ef39808f568 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -10,8 +10,15 @@ available which covers many of these same guidelines.
[[base-branch]]
=== Decide which branch to base your work on.
-In general, always base your work on the oldest branch that your
-change is relevant to.
+The following branches are the typical starting points for new work:
+
+* maint
+* master
+* next
+* seen
+
+These branches are explained in detail in linkgit:gitworkflows[7].
+Choose the appropriate branch depending on the following scenarios:
* A bugfix should be based on `maint` in general. If the bug is not
present in `maint`, base it on `master`. For a bug that's not yet
--
gitgitgadget
