mirror of
https://github.com/git/git.git
synced 2024-05-09 02:06:12 +02:00
Merge branch 'la/doc-choose-starting-point'
Clarify how to choose the starting point for a new topic in developer guidance document. * la/doc-choose-starting-point: SubmittingPatches: simplify guidance for choosing a starting point SubmittingPatches: emphasize need to communicate non-default starting points SubmittingPatches: de-emphasize branches as starting points SubmittingPatches: discuss subsystems separately from git.git SubmittingPatches: reword awkward phrasing
This commit is contained in:
commit
dd68b57fc4
|
@ -3,45 +3,85 @@ Submitting Patches
|
|||
|
||||
== Guidelines
|
||||
|
||||
Here are some guidelines for people who want to contribute their code to this
|
||||
software. There is also a link:MyFirstContribution.html[step-by-step tutorial]
|
||||
Here are some guidelines for contributing back to this
|
||||
project. There is also a link:MyFirstContribution.html[step-by-step tutorial]
|
||||
available which covers many of these same guidelines.
|
||||
|
||||
[[base-branch]]
|
||||
=== Decide what to base your work on.
|
||||
[[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.
|
||||
|
||||
* Some parts of the system have dedicated maintainers with their own
|
||||
repositories (see the section "Subsystems" below). Changes to
|
||||
these parts should be based on their trees.
|
||||
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:
|
||||
|
||||
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.
|
||||
* 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
|
||||
"Subsystems" below).
|
||||
|
||||
[[separate-commits]]
|
||||
=== Make separate commits for logically separate changes.
|
||||
|
@ -317,10 +357,13 @@ Please make sure your patch does not add commented out debugging code,
|
|||
or include any extra files which do not relate to what your patch
|
||||
is trying to achieve. Make sure to review
|
||||
your patch after generating it, to ensure accuracy. Before
|
||||
sending out, please make sure it cleanly applies to the base you
|
||||
have chosen in the "Decide what to base your work on" section,
|
||||
and unless it targets the `master` branch (which is the default),
|
||||
mark your patches as such.
|
||||
sending out, please make sure it cleanly applies to the starting point you
|
||||
have chosen in the "Choose a starting point" section.
|
||||
|
||||
NOTE: From the perspective of those reviewing your patch, the `master`
|
||||
branch is the default expected starting point. So if you have chosen a
|
||||
different starting point, please communicate this choice in your cover
|
||||
letter.
|
||||
|
||||
|
||||
[[send-patches]]
|
||||
|
|
Loading…
Reference in New Issue