From: "Linus Arver via GitGitGadget" <gitgitgadget@gmail.com>
To: git@vger.kernel.org
Cc: Linus Arver <linusa@google.com>
Subject: [PATCH v3 0/5] SubmittingPatches: clarify which branch to use
Date: Wed, 26 Jul 2023 03:04:56 +0000 [thread overview]
Message-ID: <pull.1556.v3.git.1690340701.gitgitgadget@gmail.com> (raw)
In-Reply-To: <pull.1556.v2.git.1689314493.gitgitgadget@gmail.com>
This series rewords the "base-branch" section (now renamed to
"choose-starting-point") to be more informative in general to new
contributors, who may not be as familiar with the various integration
branches. Other smaller cleanups and improvements were made along the way.
Updates in v3
=============
* We add a little more detail about when you'd want to use the tip of a
maintenance track (e.g., maint-2.30) instead of maint.
* The language about the instability of "next" and "seen" has been
de-emphasized, in favor of saying that these branches just have lots of
other topics (some not ready) in it.
Updates in v2
=============
* The language about choosing the "oldest" branch was retained, and
expanded. It turns out that this language is also present in
gitworkflows, however the meaning of the word "oldest" was not explained
properly in the "base-branch" section. This has been addressed.
* Rename "base-branch" to "choose-starting-point"
* Patch 04 (emphasize need to communicate non-default starting points) is
new.
Linus Arver (5):
SubmittingPatches: reword awkward phrasing
SubmittingPatches: discuss subsystems separately from git.git
SubmittingPatches: de-emphasize branches as starting points
SubmittingPatches: emphasize need to communicate non-default starting
points
SubmittingPatches: simplify guidance for choosing a starting point
Documentation/SubmittingPatches | 134 ++++++++++++++++++++++----------
1 file changed, 93 insertions(+), 41 deletions(-)
base-commit: aa9166bcc0ba654fc21f198a30647ec087f733ed
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1556%2Flistx%2Fdoc-submitting-patches-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1556/listx/doc-submitting-patches-v3
Pull-Request: https://github.com/gitgitgadget/git/pull/1556
Range-diff vs v2:
1: 08deed14d96 = 1: 08deed14d96 SubmittingPatches: reword awkward phrasing
2: 8d4b57a8704 = 2: 8d4b57a8704 SubmittingPatches: discuss subsystems separately from git.git
3: 69fef8afe64 = 3: 69fef8afe64 SubmittingPatches: de-emphasize branches as starting points
4: f8f96a79b92 = 4: f8f96a79b92 SubmittingPatches: emphasize need to communicate non-default starting points
5: 5ec91d02b7a ! 5: 1273f50c8a8 SubmittingPatches: simplify guidance for choosing a starting point
@@ Commit message
workflows, 2008-10-19).
Summary: This change simplifies the guidance by pointing users to just
- "maint" or "master". But it also gives an explanation of why that is
- preferred and what is meant by preferring "older" branches (which might
- be confusing to some because "old" here is meant in relative terms
- between these named branches, not in terms of the age of the branches
- themselves). We also add an example to illustrate why it would be a bad
- idea to use "next" as a starting point, which may not be so obvious to
- new contributors.
+ "maint" or "master" for most cases. But it also gives an explanation of
+ why that is preferred and what is meant by preferring "older"
+ branches (which might be confusing to some because "old" here is meant
+ in relative terms between these named branches, not in terms of the age
+ of the branches themselves). We also explain in detail why it would be a
+ bad idea to use "next" or "seen" as starting points, which may not be so
+ obvious to new contributors.
Helped-by: Jonathan Nieder <jrnieder@gmail.com>
Helped-by: Junio C Hamano <gitster@pobox.com>
@@ Documentation/SubmittingPatches: available which covers many of these same guide
+* If you are fixing bugs in the released version, use `maint` as the
+ starting point (which may mean you have to fix things without using
+ new API features on the cutting edge that recently appeared in
-+ `master` but were not available in the released version).
++ `master` but were not available in the released version). If the bug
++ exists in an older version (e.g., commit `X` introduced the bug, and
++ `git describe --containx X` says `v2.30.0-rc2-gXXXXXX` has it), then
++ use the tip of the maintenance branch for the 2.30.x versions in the
++ `maint-2.30` branch in https://github.com/gitster/git[the maintainer's
++ repo].
+
+* Otherwise (such as if you are adding new features) use `master`.
+
+This also means that `next` or `seen` are inappropriate starting points
+for your work, if you want your work to have a realistic chance of
-+graduating to `master`. They are simply not designed to provide a
-+stable base for new work, because they are (by design) frequently
-+re-integrated with incoming patches on the mailing list and force-pushed
-+to replace previous versions of these branches.
++graduating to `master`. They are simply not designed to be used as a
++base for new work; they are only there to make sure that topics in
++flight work well together. This is why both `next` and `seen` are
++frequently re-integrated with incoming patches on the mailing list and
++force-pushed to replace previous versions of themselves. A topic that is
++literally built on top of `next` cannot be merged to 'master' without
++dragging in all the other topics in `next`, some of which may not be
++ready.
+
+For example, if you are making tree-wide changes, while somebody else is
+also making their own tree-wide changes, your work may have severe
--
gitgitgadget
next prev parent reply other threads:[~2023-07-26 3:05 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 ` [PATCH 4/5] SubmittingPatches: remove confusing guidance about base branches Linus Arver via GitGitGadget
2023-07-08 5:48 ` 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 ` Linus Arver via GitGitGadget [this message]
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=pull.1556.v3.git.1690340701.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).