git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[PATCH 4/5] SubmittingPatches: remove confusing guidance about base branches

From
LGLinus Arver via GitGitGadget <gitgitgadget@gmail.com>
Date
Jul 8, 2023, 01:05 UTC
Message-ID
<55bed55cb8859ac7b5b4f464232258f410b4d202.1688778359.git.gitgitgadget@gmail.com>
In-Reply-To
<pull.1556.git.1688778359.gitgitgadget@gmail.com>
From: Linus Arver <linusa@google.com>

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@gmail.com>
Signed-off-by: Linus Arver <linusa@google.com>
---
 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
Previous: Linus Arver via GitGitGadgetNext: Junio C Hamano
Message 9 of 38 in “SubmittingPatches: clarify which branch to use”
  1. 0/5 SubmittingPatches: clarify which branch to useLinus Arver via GitGitGadget, Jul 8, 2023
  2. 2/5 SubmittingPatches: be more explicitLinus Arver via GitGitGadget, Jul 8, 2023
  3. Junio C HamanoJul 8, 2023
  4. Linus ArverJul 13, 2023
  5. Junio C HamanoJul 13, 2023
  6. 1/5 SubmittingPatches: reword awkward phrasingLinus Arver via GitGitGadget, Jul 8, 2023
  7. Junio C HamanoJul 8, 2023
  8. 3/5 SubmittingPatches: discuss subsystems separately from git.gitLinus Arver via GitGitGadget, Jul 8, 2023
  9. 4/5 SubmittingPatches: remove confusing guidance about base branchesLinus Arver via GitGitGadget, Jul 8, 2023
  10. Junio C HamanoJul 8, 2023
  11. Linus ArverJul 13, 2023
  12. 5/5 SubmittingPatches: define topic branchesLinus Arver via GitGitGadget, Jul 8, 2023
  13. 0/5 SubmittingPatches: clarify which branch to useLinus Arver via GitGitGadget, Jul 14, 2023
  14. 2/5 SubmittingPatches: discuss subsystems separately from git.gitLinus Arver via GitGitGadget, Jul 14, 2023
  15. 1/5 SubmittingPatches: reword awkward phrasingLinus Arver via GitGitGadget, Jul 14, 2023
  16. 3/5 SubmittingPatches: de-emphasize branches as starting pointsLinus Arver via GitGitGadget, Jul 14, 2023
  17. 4/5 SubmittingPatches: emphasize need to communicate non-default starting pointsLinus Arver via GitGitGadget, Jul 14, 2023
  18. 5/5 SubmittingPatches: simplify guidance for choosing a starting pointLinus Arver via GitGitGadget, Jul 14, 2023
  19. Junio C HamanoJul 14, 2023
  20. Linus ArverJul 26, 2023
  21. Linus ArverJul 26, 2023
  22. Junio C HamanoJul 26, 2023
  23. 0/5 SubmittingPatches: clarify which branch to useLinus Arver via GitGitGadget, Jul 26, 2023
  24. 1/5 SubmittingPatches: reword awkward phrasingLinus Arver via GitGitGadget, Jul 26, 2023
  25. 4/5 SubmittingPatches: emphasize need to communicate non-default starting pointsLinus Arver via GitGitGadget, Jul 26, 2023
  26. 2/5 SubmittingPatches: discuss subsystems separately from git.gitLinus Arver via GitGitGadget, Jul 26, 2023
  27. 5/5 SubmittingPatches: simplify guidance for choosing a starting pointLinus Arver via GitGitGadget, Jul 26, 2023
  28. 3/5 SubmittingPatches: de-emphasize branches as starting pointsLinus Arver via GitGitGadget, Jul 26, 2023
  29. Junio C HamanoJul 26, 2023
  30. Linus ArverJul 26, 2023
  31. 6/5 SubmittingPatches: choice of base for fixing an older maintenance trackJunio C Hamano, Jul 26, 2023
  32. Eric SunshineJul 26, 2023
  33. Junio C HamanoJul 26, 2023
  34. 7/5 SubmittingPatches: explain why 'next' and above are inappropriate baseJunio C Hamano, Jul 26, 2023
  35. Linus ArverJul 27, 2023
  36. 8/5 SubmittingPatches: use of older maintenance tracks is an exceptionJunio C Hamano, Jul 26, 2023
  37. Linus ArverJul 27, 2023
  38. Junio C HamanoJul 27, 2023

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.