From: "Linus Arver via GitGitGadget" <gitgitgadget@gmail.com>
To: git@vger.kernel.org
Cc: Linus Arver <linusa@google.com>, Linus Arver <linusa@google.com>
Subject: [PATCH 4/5] SubmittingPatches: remove confusing guidance about base branches
Date: Sat, 08 Jul 2023 01:05:58 +0000 [thread overview]
Message-ID: <55bed55cb8859ac7b5b4f464232258f410b4d202.1688778359.git.gitgitgadget@gmail.com> (raw)
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
next prev parent reply other threads:[~2023-07-08 1:06 UTC|newest]
Thread overview: 38+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-07-08 1:05 [PATCH 0/5] SubmittingPatches: clarify which branch to use Linus Arver via GitGitGadget
2023-07-08 1:05 ` [PATCH 1/5] SubmittingPatches: reword awkward phrasing Linus Arver via GitGitGadget
2023-07-08 5:37 ` Junio C Hamano
2023-07-08 1:05 ` [PATCH 2/5] SubmittingPatches: be more explicit Linus Arver via GitGitGadget
2023-07-08 5:36 ` Junio C Hamano
2023-07-13 21:03 ` Linus Arver
2023-07-13 21:10 ` Junio C Hamano
2023-07-08 1:05 ` [PATCH 3/5] SubmittingPatches: discuss subsystems separately from git.git Linus Arver via GitGitGadget
2023-07-08 1:05 ` Linus Arver via GitGitGadget [this message]
2023-07-08 5:48 ` [PATCH 4/5] SubmittingPatches: remove confusing guidance about base branches Junio C Hamano
2023-07-13 21:54 ` Linus Arver
2023-07-08 1:05 ` [PATCH 5/5] SubmittingPatches: define topic branches Linus Arver via GitGitGadget
2023-07-14 6:01 ` [PATCH v2 0/5] SubmittingPatches: clarify which branch to use Linus Arver via GitGitGadget
2023-07-14 6:01 ` [PATCH v2 1/5] SubmittingPatches: reword awkward phrasing Linus Arver via GitGitGadget
2023-07-14 6:01 ` [PATCH v2 2/5] SubmittingPatches: discuss subsystems separately from git.git Linus Arver via GitGitGadget
2023-07-14 6:01 ` [PATCH v2 3/5] SubmittingPatches: de-emphasize branches as starting points Linus Arver via GitGitGadget
2023-07-14 6:01 ` [PATCH v2 4/5] SubmittingPatches: emphasize need to communicate non-default " Linus Arver via GitGitGadget
2023-07-14 6:01 ` [PATCH v2 5/5] SubmittingPatches: simplify guidance for choosing a starting point Linus Arver via GitGitGadget
2023-07-14 17:31 ` Junio C Hamano
2023-07-26 1:36 ` Linus Arver
2023-07-26 2:31 ` Linus Arver
2023-07-26 4:41 ` Junio C Hamano
2023-07-26 3:04 ` [PATCH v3 0/5] SubmittingPatches: clarify which branch to use Linus Arver via GitGitGadget
2023-07-26 3:04 ` [PATCH v3 1/5] SubmittingPatches: reword awkward phrasing Linus Arver via GitGitGadget
2023-07-26 3:04 ` [PATCH v3 2/5] SubmittingPatches: discuss subsystems separately from git.git Linus Arver via GitGitGadget
2023-07-26 3:04 ` [PATCH v3 3/5] SubmittingPatches: de-emphasize branches as starting points Linus Arver via GitGitGadget
2023-07-26 3:05 ` [PATCH v3 4/5] SubmittingPatches: emphasize need to communicate non-default " Linus Arver via GitGitGadget
2023-07-26 3:05 ` [PATCH v3 5/5] SubmittingPatches: simplify guidance for choosing a starting point Linus Arver via GitGitGadget
2023-07-26 5:15 ` [PATCH v3 0/5] SubmittingPatches: clarify which branch to use Junio C Hamano
2023-07-26 17:19 ` Linus Arver
2023-07-26 5:16 ` [PATCH v3 6/5] SubmittingPatches: choice of base for fixing an older maintenance track Junio C Hamano
2023-07-26 5:40 ` Eric Sunshine
2023-07-26 16:36 ` Junio C Hamano
2023-07-26 5:17 ` [PATCH 7/5] SubmittingPatches: explain why 'next' and above are inappropriate base Junio C Hamano
2023-07-27 19:26 ` Linus Arver
2023-07-26 5:21 ` [PATCH 8/5] SubmittingPatches: use of older maintenance tracks is an exception Junio C Hamano
2023-07-27 19:35 ` Linus Arver
2023-07-27 20:08 ` Junio C Hamano
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=55bed55cb8859ac7b5b4f464232258f410b4d202.1688778359.git.gitgitgadget@gmail.com \
--to=gitgitgadget@gmail.com \
--cc=git@vger.kernel.org \
--cc=linusa@google.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).