mirrors/git
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

SubmittingPatches: simplify guidance for choosing a starting point

Browse Source 
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>
This commit is contained in:
Linus Arver
2023-07-14 06:01:33 +00:00
committed by Junio C Hamano
parent 5c98149ce4
commit 0a02ca2383
1 changed files with 63 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

86
Documentation/SubmittingPatches
View File

@ -10,34 +10,74 @@ 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.
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).
* 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.
There are several important branches to be aware of. Namely, there are
four integration branches as discussed in linkgit:gitworkflows[7]:
* 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..`.
* maint
* master
* next
* seen
* 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.
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`.
* 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).
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.
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).
* 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.
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