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

Re: [PATCH v2 5/5] SubmittingPatches: simplify guidance for choosing a starting point

From
Junio C Hamano <gitster@pobox.com>
Date
Jul 14, 2023, 17:31 UTC
Message-ID
<xmqq5y6mpfhm.fsf@gitster.g>
In-Reply-To
<5ec91d02b7ae767cc9b2395e1c0fa10e1424c0c5.1689314493.git.gitgitgadget@gmail.com>
"Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:
Show 11 quoted lines
> +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[*].

Show 8 quoted lines
> +* 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 ...
Show 21 quoted lines
> +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.
Previous: Linus Arver via GitGitGadgetNext: Linus Arver
Message 19 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.