From: Junio C Hamano <gitster@pobox.com>
To: "Linus Arver via GitGitGadget" <gitgitgadget@gmail.com>
Cc: git@vger.kernel.org, Linus Arver <linusa@google.com>
Subject: Re: [PATCH v2 5/5] SubmittingPatches: simplify guidance for choosing a starting point
Date: Fri, 14 Jul 2023 10:31:01 -0700 [thread overview]
Message-ID: <xmqq5y6mpfhm.fsf@gitster.g> (raw)
In-Reply-To: <5ec91d02b7ae767cc9b2395e1c0fa10e1424c0c5.1689314493.git.gitgitgadget@gmail.com> (Linus Arver via GitGitGadget's message of "Fri, 14 Jul 2023 06:01:33 +0000")
"Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:
> +There is one guiding principle for choosing the right starting point: in
> +general, always base your work on the oldest integration branch that
> +your change is relevant to (see "Merge upwards" in
> +linkgit:gitworkflows[7]). What this principle means is that for the
> +vast majority of cases, the starting point for new work should be the
> +latest HEAD commit of `maint` or `master` based on the following cases:
> +
> +* 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).
I think this is technically not optimal, but is good enough for the
sake of simplicity and brevity[*].
> +* 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.
"unstable" is not the primary reason why you shouldn't build on
'next'. It is "your work, if queued on 'next', cannot be merged to
'master' without pulling all the other undercooked stuff still in
'next'", as you describe in the next paragraph. But that is
different from being unstable. I'd suggest to use something like
this instead:
... not designed to be used as a base for new work---they
are there only to make sure that topics in flight work well
together. A topic that is literally built on top of 'next'
cannot be merged to 'master' without dragging all the other
topics in 'next', some of which may not be ready. In
addition, `seen` is frequently re-integrated with incoming
patches ...
> +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
> +overlap with the other person's work. This situation may tempt you to
> +use `next` as your starting point (because it would have the other
> +person's work included in it), but doing so would mean you'll not only
> +depend on the other person's work, but all the other random things from
> +other contributors that are already integrated into `next`. And as soon
> +as `next` is updated with a new version, all of your work will need to
> +be rebased anyway in order for them to be cleanly applied by the
> +maintainer.
> +
> +Under truly exceptional circumstances where you absolutely must depend
> +on a select few topic branches that are already in `next` but not in
> +`master`, you may want to create your own custom base-branch by forking
> +`master` and merging the required topic branches to it. You could then
> +work on top of this base-branch. But keep in mind that this base-branch
> +would only be known privately to you. So when you are ready to send
> +your patches to the list, be sure to communicate how you created it in
> +your cover letter. This critical piece of information would allow
> +others to recreate your base-branch on their end in order for them to
> +try out your work.
Very well written.
Thanks, will queue.
[Footnote]
* An very old but still severe bug in tagged versions would want to
be fixed ideally not on top of 'maint' but on top of the latest
tagged version in the same maintenance track. E.g. if the commit
X introduced the bug, you may ask "git describe --contains X" the
oldest version the commit appears in, say "v2.30.0-rc2-gXXXXXX".
Then you would run "git checkout -b fix v2.30.9" to start the
branch to fix it.
next prev parent reply other threads:[~2023-07-14 17:31 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 [this message]
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=xmqq5y6mpfhm.fsf@gitster.g \
--to=gitster@pobox.com \
--cc=git@vger.kernel.org \
--cc=gitgitgadget@gmail.com \
--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).