diff options
Diffstat (limited to 'SubmittingPatches.html')
| -rw-r--r-- | SubmittingPatches.html | 141 |
1 files changed, 106 insertions, 35 deletions
diff --git a/SubmittingPatches.html b/SubmittingPatches.html index 9fafcac83..5e37659cd 100644 --- a/SubmittingPatches.html +++ b/SubmittingPatches.html @@ -735,65 +735,127 @@ asciidoc.install(); <body class="article">
<div id="header">
<h1>Submitting Patches</h1>
-<span id="revdate">2023-08-02</span>
+<span id="revdate">2023-08-04</span>
</div>
<div id="content">
<div class="sect1">
<h2 id="_guidelines">Guidelines</h2>
<div class="sectionbody">
-<div class="paragraph"><p>Here are some guidelines for people who want to contribute their code to this
-software. There is also a <a href="MyFirstContribution.html">step-by-step tutorial</a>
+<div class="paragraph"><p>Here are some guidelines for contributing back to this
+project. There is also a <a href="MyFirstContribution.html">step-by-step tutorial</a>
available which covers many of these same guidelines.</p></div>
<div class="sect2">
-<h3 id="base-branch">Decide what to base your work on.</h3>
-<div class="paragraph"><p>In general, always base your work on the oldest branch that your
-change is relevant to.</p></div>
+<h3 id="choose-starting-point">Choose a starting point.</h3>
+<div class="paragraph"><p>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).</p></div>
+<div class="paragraph"><p>There are several important branches to be aware of. Namely, there are
+four integration branches as discussed in <a href="gitworkflows.html">gitworkflows(7)</a>:</p></div>
<div class="ulist"><ul>
<li>
<p>
-A bugfix should be based on <code>maint</code> in general. If the bug is not
- present in <code>maint</code>, base it on <code>master</code>. For a bug that’s not yet
- in <code>master</code>, find the topic that introduces the regression, and
- base your work on the tip of the topic.
+maint
</p>
</li>
<li>
<p>
-A new feature should be based on <code>master</code> in general. If the new
- feature depends on other topics that are in <code>next</code>, but not in
- <code>master</code>, fork a branch from the tip of <code>master</code>, merge these topics
- to the branch, and work on that branch. You can remind yourself of
- how you prepared the base with <code>git log --first-parent master..</code>.
+master
</p>
</li>
<li>
<p>
-Corrections and enhancements to a topic not yet in <code>master</code> should
- be based on the tip of that topic. If the topic has not been merged
- to <code>next</code>, it’s alright to add a note to squash minor corrections
- into the series.
+next
</p>
</li>
<li>
<p>
-In the exceptional case that a new feature depends on several topics
- not in <code>master</code>, start working on <code>next</code> or <code>seen</code> 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).
+seen
</p>
</li>
+</ul></div>
+<div class="paragraph"><p>The branches lower on the list are typically descendants of the ones
+that come before it. For example, <code>maint</code> is an "older" branch than
+<code>master</code> because <code>master</code> usually has patches (commits) on top of
+<code>maint</code>.</p></div>
+<div class="paragraph"><p>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 <code>git log
+--first-parent master..seen</code> and look for the merge commit. The second
+parent of this commit is the tip of the topic branch.</p></div>
+<div class="paragraph"><p>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
+<a href="gitworkflows.html">gitworkflows(7)</a>). 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 <code>maint</code> or <code>master</code> based on the following cases:</p></div>
+<div class="ulist"><ul>
<li>
<p>
-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.
+If you are fixing bugs in the released version, use <code>maint</code> 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
+ <code>master</code> but were not available in the released version).
+</p>
+</li>
+<li>
+<p>
+Otherwise (such as if you are adding new features) use <code>master</code>.
</p>
</li>
</ul></div>
-<div class="paragraph"><p>To find the tip of a topic branch, run <code>git log --first-parent
-master..seen</code> and look for the merge commit. The second parent of this
-commit is the tip of the topic branch.</p></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">In exceptional cases, a bug that was introduced in an old
+version may have to be fixed for users of releases that are much older
+than the recent releases. <code>git describe --contains X</code> may describe
+<code>X</code> as <code>v2.30.0-rc2-gXXXXXX</code> for the commit <code>X</code> that introduced the
+bug, and the bug may be so high-impact that we may need to issue a new
+maintenance release for Git 2.30.x series, when "Git 2.41.0" is the
+current release. In such a case, you may want to use the tip of the
+maintenance branch for the 2.30.x series, which may be available in the
+<code>maint-2.30</code> branch in <a href="https://github.com/gitster/git">the maintainer’s
+"broken out" repo</a>.</td>
+</tr></table>
+</div>
+<div class="paragraph"><p>This also means that <code>next</code> or <code>seen</code> are inappropriate starting points
+for your work, if you want your work to have a realistic chance of
+graduating to <code>master</code>. 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 <code>next</code> and <code>seen</code> 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 <code>next</code> cannot be merged to <code>master</code> without
+dragging in all the other topics in <code>next</code>, some of which may not be
+ready.</p></div>
+<div class="paragraph"><p>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 <code>next</code> 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 <code>next</code>. And as soon
+as <code>next</code> 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.</p></div>
+<div class="paragraph"><p>Under truly exceptional circumstances where you absolutely must depend
+on a select few topic branches that are already in <code>next</code> but not in
+<code>master</code>, you may want to create your own custom base-branch by forking
+<code>master</code> 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.</p></div>
+<div class="paragraph"><p>Finally, note that some parts of the system have dedicated maintainers
+with their own separate source code repositories (see the section
+"Subsystems" below).</p></div>
</div>
<div class="sect2">
<h3 id="separate-commits">Make separate commits for logically separate changes.</h3>
@@ -1096,10 +1158,19 @@ receiving end can handle them just fine.</p></div> 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 <code>master</code> branch (which is the default),
-mark your patches as such.</p></div>
+sending out, please make sure it cleanly applies to the starting point you
+have chosen in the "Choose a starting point" section.</p></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">From the perspective of those reviewing your patch, the <code>master</code>
+branch is the default expected starting point. So if you have chosen a
+different starting point, please communicate this choice in your cover
+letter.</td>
+</tr></table>
+</div>
</div>
<div class="sect2">
<h3 id="send-patches">Sending your patches.</h3>
@@ -1447,7 +1518,7 @@ this problem around.</p></div> <div id="footer">
<div id="footer-text">
Last updated
- 2023-06-01 01:26:46 PDT
+ 2023-08-04 12:03:21 PDT
</div>
</div>
</body>
|