SubmittingPatches: simplify guidance for choosing a starting point
Background: 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 the following named branches: "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 guidance was probably taken from existing similar language introduced in the "Merge upwards" section of gitworkflows in f948dd8992 (Documentation: add manpage about 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. Helped-by: Jonathan Nieder <jrnieder@gmail.com> Helped-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Linus Arver <linusa@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Linus Arver committed
Jul 14, 2023 at 06:01 UTC
0a02ca2383455e40cfc0b1c0818479c2d36fe6cd
1 file changed
+68
-28
Documentation/SubmittingPatches
+68
-28
@@ -10,34 +10,74 @@ available which covers many of these same guidelines.
10
[[choose-starting-point]]
11
=== Choose a starting point.
12
13
-In general, always base your work on the oldest branch that your
14
-change is relevant to.
15
-
16
-* A bugfix should be based on `maint` in general. If the bug is not
17
- present in `maint`, base it on `master`. For a bug that's not yet
18
- in `master`, find the topic that introduces the regression, and
19
- base your work on the tip of the topic.
20
-
21
-* A new feature should be based on `master` in general. If the new
22
- feature depends on other topics that are in `next`, but not in
23
- `master`, fork a branch from the tip of `master`, merge these topics
24
- to the branch, and work on that branch. You can remind yourself of
25
- how you prepared the base with `git log --first-parent master..`.
26
-
27
-* Corrections and enhancements to a topic not yet in `master` should
28
- be based on the tip of that topic. If the topic has not been merged
29
- to `next`, it's alright to add a note to squash minor corrections
30
- into the series.
31
-
32
-* In the exceptional case that a new feature depends on several topics
33
- not in `master`, start working on `next` or `seen` privately and
34
- send out patches only for discussion. Once your new feature starts
35
- to stabilize, you would have to rebase it (see the "depends on other
36
- topics" above).
37
-
38
-To find the tip of a topic branch, run `git log --first-parent
39
-master..seen` and look for the merge commit. The second parent of this
40
-commit is the tip of the topic branch.
13
+As a preliminary step, you must first choose a starting point for your
14
+work. Typically this means choosing a branch, although technically
15
+speaking it is actually a particular commit (typically the HEAD, or tip,
16
+of the branch).
17
+
18
+There are several important branches to be aware of. Namely, there are
19
+four integration branches as discussed in linkgit:gitworkflows[7]:
20
+
21
+* maint
22
+* master
23
+* next
24
+* seen
25
+
26
+The branches lower on the list are typically descendants of the ones
27
+that come before it. For example, `maint` is an "older" branch than
28
+`master` because `master` usually has patches (commits) on top of
29
+`maint`.
30
+
31
+There are also "topic" branches, which contain work from other
32
+contributors. Topic branches are created by the Git maintainer (in
33
+their fork) to organize the current set of incoming contributions on
34
+the mailing list, and are itemized in the regular "What's cooking in
35
+git.git" announcements. To find the tip of a topic branch, run `git log
36
+--first-parent master..seen` and look for the merge commit. The second
37
+parent of this commit is the tip of the topic branch.
38
+
39
+There is one guiding principle for choosing the right starting point: in
40
+general, always base your work on the oldest integration branch that
41
+your change is relevant to (see "Merge upwards" in
42
+linkgit:gitworkflows[7]). What this principle means is that for the
43
+vast majority of cases, the starting point for new work should be the
44
+latest HEAD commit of `maint` or `master` based on the following cases:
45
+
46
+* If you are fixing bugs in the released version, use `maint` as the
47
+ starting point (which may mean you have to fix things without using
48
+ new API features on the cutting edge that recently appeared in
49
+ `master` but were not available in the released version).
50
+
51
+* Otherwise (such as if you are adding new features) use `master`.
52
+
53
+This also means that `next` or `seen` are inappropriate starting points
54
+for your work, if you want your work to have a realistic chance of
55
+graduating to `master`. They are simply not designed to provide a
56
+stable base for new work, because they are (by design) frequently
57
+re-integrated with incoming patches on the mailing list and force-pushed
58
+to replace previous versions of these branches.
59
+
60
+For example, if you are making tree-wide changes, while somebody else is
61
+also making their own tree-wide changes, your work may have severe
62
+overlap with the other person's work. This situation may tempt you to
63
+use `next` as your starting point (because it would have the other
64
+person's work included in it), but doing so would mean you'll not only
65
+depend on the other person's work, but all the other random things from
66
+other contributors that are already integrated into `next`. And as soon
67
+as `next` is updated with a new version, all of your work will need to
68
+be rebased anyway in order for them to be cleanly applied by the
69
+maintainer.
70
+
71
+Under truly exceptional circumstances where you absolutely must depend
72
+on a select few topic branches that are already in `next` but not in
73
+`master`, you may want to create your own custom base-branch by forking
74
+`master` and merging the required topic branches to it. You could then
75
+work on top of this base-branch. But keep in mind that this base-branch
76
+would only be known privately to you. So when you are ready to send
77
+your patches to the list, be sure to communicate how you created it in
78
+your cover letter. This critical piece of information would allow
79
+others to recreate your base-branch on their end in order for them to
80
+try out your work.
81
82
Finally, note that some parts of the system have dedicated maintainers
83
with their own separate source code repositories (see the section