@@ -10,34 +10,83 @@ available which covers many of these same guidelines.
[[choose-starting-point]]
=== Choose a starting point.
-In general, always base your work on the oldest branch that your
-change is relevant to.
-
-* 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
- in `master`, find the topic that introduces the regression, and
- base your work on the tip of the topic.
-
-* A new feature should be based on `master` in general. If the new
- feature depends on other topics that are in `next`, but not in
- `master`, fork a branch from the tip of `master`, merge these topics
- to the branch, and work on that branch. You can remind yourself of
- how you prepared the base with `git log --first-parent master..`.
-
-* Corrections and enhancements to a topic not yet in `master` should
- be based on the tip of that topic. If the topic has not been merged
- to `next`, it's alright to add a note to squash minor corrections
- into the series.
-
-* In the exceptional case that a new feature depends on several topics
- not in `master`, start working on `next` or `seen` privately and
- send out patches only for discussion. Once your new feature starts
- to stabilize, you would have to rebase it (see the "depends on other
- topics" above).
-
-To find the tip of a topic branch, run `git log --first-parent
-master..seen` and look for the merge commit. The second parent of this
-commit is the tip of the topic branch.
+As a preliminary step, you must first choose a starting point for your
+work. Typically this means choosing a branch, although technically
+speaking it is actually a particular commit (typically the HEAD, or tip,
+of the branch).
+
+There are several important branches to be aware of. Namely, there are
+four integration branches as discussed in linkgit:gitworkflows[7]:
+
+* maint
+* master
+* next
+* seen
+
+The branches lower on the list are typically descendants of the ones
+that come before it. For example, `maint` is an "older" branch than
+`master` because `master` usually has patches (commits) on top of
+`maint`.
+
+There are also "topic" branches, which contain work from other
+contributors. Topic branches are created by the Git maintainer (in
+their fork) to organize the current set of incoming contributions on
+the mailing list, and are itemized in the regular "What's cooking in
+git.git" announcements. To find the tip of a topic branch, run `git log
+--first-parent master..seen` and look for the merge commit. The second
+parent of this commit is the tip of the topic branch.
+
+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). 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 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
+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.
Finally, note that some parts of the system have dedicated maintainers
with their own separate source code repositories (see the section