Author: buildbot
Date: Thu Oct 19 16:03:51 2017
New Revision: 1019794
Log:
Staging update by buildbot for thrift
Modified:
websites/staging/thrift/trunk/content/ (props changed)
websites/staging/thrift/trunk/content/docs/HowToContribute.html
Propchange: websites/staging/thrift/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Thu Oct 19 16:03:51 2017
@@ -1 +1 @@
-1812647
+1812649
Modified: websites/staging/thrift/trunk/content/docs/HowToContribute.html
==============================================================================
--- websites/staging/thrift/trunk/content/docs/HowToContribute.html (original)
+++ websites/staging/thrift/trunk/content/docs/HowToContribute.html Thu Oct 19
16:03:51 2017
@@ -84,72 +84,93 @@
visibility: hidden;
}
h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink,
h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink,
dt:hover > .elementid-permalink { visibility: visible }</style>
-<h2 id="how-to-contribute">How to contribute<a class="headerlink"
href="#how-to-contribute" title="Permanent link">¶</a></h2>
+<h1 id="how-to-contribute">How to Contribute<a class="headerlink"
href="#how-to-contribute" title="Permanent link">¶</a></h1>
+<p>Thank you for your interest in contributing to the Apache Thrift project!
Information on why and how to contribute is available on the Apache Software
Foundation (ASF) web site. In particular, we recommend the following to become
acquainted with Apache Contributions:</p>
+<ul>
+<li><a href="http://www.apache.org/dev/contributors";>Contributors Tech
Guide</a></li>
+<li><a href="http://www.apache.org/foundation/getinvolved.html";>Get
involved!</a></li>
+<li><a
href="http://www.apache.org/licenses/LICENSE-2.0.html#contributions";>Legal
aspects on Submission of Contributions (Patches)</a></li>
+</ul>
+<h2 id="if-you-want-to-review-open-issues">If you want to review open
issues...<a class="headerlink" href="#if-you-want-to-review-open-issues"
title="Permanent link">¶</a></h2>
<ol>
-<li>Help to review and verify existing patches</li>
-<li>Make sure your issue is not all ready in the <a
href="http://issues.apache.org/jira/browse/THRIFT";>Jira issue tracker</a></li>
-<li>If not, create a ticket describing the change you're proposing in the <a
href="http://issues.apache.org/jira/browse/THRIFT";>Jira issue tracker</a></li>
-<li>Contribute your patch using one of the two methods below</li>
+<li>Review the <a href="https://github.com/apache/thrift/pulls";>GitHub Pull
Request Backlog</a>. Code reviews are open to all.</li>
+<li>Review the <a href="http://issues.apache.org/jira/browse/THRIFT";>Jira
issue tracker</a>. You can search for tickets relating to languages you are
interested in or currently using with thrift, for example a Jira search (Issues
-> Search For Issues) query of <code>project = THRIFT AND component in
("Erlang - Library") and status not in (resolved, closed)</code> will locate
all the open Erlang Library issues.</li>
</ol>
-<h3 id="contributing-via-a-patch">Contributing via a patch<a
class="headerlink" href="#contributing-via-a-patch" title="Permanent
link">¶</a></h3>
+<h2 id="if-you-discovered-a-defect">If you discovered a defect...<a
class="headerlink" href="#if-you-discovered-a-defect" title="Permanent
link">¶</a></h2>
<ol>
-<li>
-<p>Check out the latest version of the source code</p>
-</li>
-<li>
-<p>git clone https://git-wip-us.apache.org/repos/asf/thrift.git thrift</p>
-</li>
-<li>
-<p>Modify the source to include the improvement/bugfix</p>
-</li>
-<li>
-<p>Remember to provide <em>tests</em> for all submited changes</p>
-</li>
-<li>When bugfixing: add test that will isolate bug <em>before</em> applying
change that fixes it</li>
-<li>
-<p>Verify that you follow <a href="/docs/coding_standards">Thrift Coding
Standards</a> (you can run 'make style', which ensures proper format for some
languages)</p>
-</li>
-<li>
-<p>Create a patch from project root directory (e.g. you@dev:~/thrift $ ):</p>
-</li>
-<li>
-<p>git diff > ../thrift-XXX-my-new-feature.patch</p>
-</li>
-<li>
-<p>Attach the newly generated patch to the issue</p>
-</li>
-<li>Wait for other contributors or committers to review your new addition</li>
-<li>Wait for a committer to commit your patch</li>
+<li>Check to see if the issue is already in the <a
href="http://issues.apache.org/jira/browse/THRIFT";>Jira issue tracker</a>.</li>
+<li>If not, create a ticket describing the change you're proposing in the Jira
issue tracker.</li>
+<li>Contribute your code changes using the GitHub pull request method:</li>
</ol>
-<h3 id="contributing-via-github-pull-requests">Contributing via GitHub pull
requests<a class="headerlink" href="#contributing-via-github-pull-requests"
title="Permanent link">¶</a></h3>
+<h2 id="contributing-via-github-pull-requests">Contributing via GitHub pull
requests<a class="headerlink" href="#contributing-via-github-pull-requests"
title="Permanent link">¶</a></h2>
+<p>This is the preferred method of submitting changes. When you submit a pull
request through github, it activates the continuous integration (CI) build
systems at Appveyor and Travis to build your changes on a variety of Windows
and Linux configurations and run all the test suites.</p>
<ol>
-<li>Create a fork for http://github.com/apache/thrift</li>
-<li>Create a branch for your changes(best practice is issue as branch name,
e.g. THRIFT-9999)</li>
+<li>Create a fork in your GitHub account of
http://github.com/apache/thrift</li>
+<li>Clone the fork to your development system.</li>
+<li>Create a branch for your changes (best practice is issue as branch name,
e.g. THRIFT-9999).</li>
<li>
-<p>Modify the source to include the improvement/bugfix</p>
-</li>
-<li>
-<p>Remember to provide <em>tests</em> for all submited changes</p>
-</li>
-<li>When bugfixing: add test that will isolate bug <em>before</em> applying
change that fixes it</li>
-<li>Verify that you follow <a href="/docs/coding_standards">Thrift Coding
Standards</a> (you can run 'make style', which ensures proper format for some
languages)</li>
-<li>
-<p>Verify that your change works on other platforms by adding a GitHub service
hook to <a
href="http://docs.travis-ci.com/user/getting-started/#Step-one%3A-Sign-in";>Travis
CI</a> and <a href="http://www.appveyor.com/docs";>AppVeyor</a></p>
+<p>Modify the source to include the improvement/bugfix, and:</p>
+<ul>
+<li>Remember to provide <em>tests</em> for all submitted changes!</li>
+<li>Use test-driven development (TDD): add a test that will isolate the bug
<em>before</em> applying a change that fixes it.</li>
+<li>Verify that you follow <a href="/docs/coding_standards">Thrift Coding
Standards</a> (you can run 'make style', which ensures proper format for some
languages).</li>
+<li>[<em>optional</em>] Verify that your change works on other platforms by
adding a GitHub service hook to <a
href="http://docs.travis-ci.com/user/getting-started/#Step-one%3A-Sign-in";>Travis
CI</a> and <a href="http://www.appveyor.com/docs";>AppVeyor</a>. You can use
this technique to run the Thrift CI jobs in your account to check your changes
before they are made public. Every GitHub pull request into Thrift will run
the full CI build and test suite on your changes.</li>
+</ul>
</li>
<li>
-<p>Commit and push changes to your branch (please use issue name and
description as commit title, e.g. THRIFT-9999 make it perfect)</p>
+<p>Squash your changes to a single commit. This is very important as it makes
the process of applying your commit upstream much easier.</p>
</li>
-<li>Issue a pull request with the jira ticket number you are working on in
it's name</li>
-<li>Wait for other contributors or committers to review your new addition</li>
-<li>Wait for a committer to commit your patch</li>
+<li>Commit and push changes to your branch (please use issue name and
description as commit title, e.g. "THRIFT-9999: make it perfect").</li>
+<li>Use GitHub to create a pull request going from your branch to
apache:master. Ensure that the Jira ticket number is at the beginning of the
title of your pull request, same as the commit title.</li>
+<li>Wait for other contributors or committers to review your new addition, and
for a CI build to complete.</li>
+<li>Wait for a committer to commit your patch. You can nudge the committers
if necessary by sending a message to the <a
href="https://thrift.apache.org/mailing";>Apache Thrift mailing list</a>.</li>
</ol>
-<h3 id="more-info">More info<a class="headerlink" href="#more-info"
title="Permanent link">¶</a></h3>
-<p>Plenty of information on why and how to contribute is available on the
Apache Software Foundation (ASF) web site. In particular, we recommend the
following:</p>
-<ul>
-<li><a href="http://www.apache.org/dev/contributors";>Contributors Tech
Guide</a></li>
-<li><a href="http://www.apache.org/foundation/getinvolved.html";>Get
involved!</a></li>
-<li><a
href="http://www.apache.org/licenses/LICENSE-2.0.html#contributions";>Legal
aspects on Submission of Contributions (Patches)</a></li>
-</ul>
+<h2 id="contributing-via-patch">Contributing via Patch<a class="headerlink"
href="#contributing-via-patch" title="Permanent link">¶</a></h2>
+<p>Some changes do not require a build, for example in documentation. For
changes that are not code or build related, you can submit a patch on Jira for
review. To create a patch from changes in your local directory:</p>
+<div class="codehilite"><pre><span class="n">git</span> <span
class="n">diff</span> <span class="o">></span> <span class="p">.</span><span
class="o">./</span><span class="n">THRIFT</span><span class="o">-</span><span
class="n">NNNN</span><span class="p">.</span><span class="n">patch</span>
+</pre></div>
+
+
+<p>then wait for contributors or committers to review your changes, and then
for a committer to apply your patch.</p>
+<h2 id="github-recipes-for-pull-requests">GitHub recipes for Pull Requests<a
class="headerlink" href="#github-recipes-for-pull-requests" title="Permanent
link">¶</a></h2>
+<p>Sometimes commmitters may ask you to take actions in your pull requests.
Here are some recipes that will help you accomplish those requests. These
examples assume you are working on Jira issue THRIFT-9999. You should also be
familiar with the <a
href="https://help.github.com/articles/syncing-a-fork/";>upstream</a> repository
concept.</p>
+<h3 id="squash-your-changes">Squash your changes<a class="headerlink"
href="#squash-your-changes" title="Permanent link">¶</a></h3>
+<p>If you have not submitted a pull request yet, or if you have not yet
rebased your existing pull request, you can squash all your commits down to a
single commit. This makes life easier for the committers. If your pull
request on GitHub has more than one commit, you should do this.</p>
+<ol>
+<li>Use the command <code>git log</code> to identify how many commits you made
since you began.</li>
+<li>Use the command <code>git rebase -i HEAD~N</code> where N is the number of
commits.</li>
+<li>Leave "pull" in the first line.</li>
+<li>Change all other lines from "pull" to "fixup".</li>
+<li>All your changes are now in a single commit.</li>
+</ol>
+<p>If you already have a pull request outstanding, you will need to do a
"force push" to overwrite it since you changed your commit history:</p>
+<div class="codehilite"><pre><span class="n">git</span> <span
class="n">push</span> <span class="o">-</span><span class="n">u</span> <span
class="n">origin</span> <span class="n">THRIFT</span><span
class="o">-</span>9999 <span class="o">--</span><span class="n">force</span>
+</pre></div>
+
+
+<p>A more detailed walkthrough of a squash can be found at <a
href="http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html";>Git
Ready</a>.</p>
+<h3 id="rebase-your-pull-request">Rebase your pull request<a
class="headerlink" href="#rebase-your-pull-request" title="Permanent
link">¶</a></h3>
+<p>If your pull request has a conflict with master, it needs to be rebased:</p>
+<div class="codehilite"><pre><span class="n">git</span> <span
class="n">checkout</span> <span class="n">THRIFT</span><span
class="o">-</span>9999
+<span class="n">git</span> <span class="n">rebase</span> <span
class="n">upstream</span> <span class="n">master</span>
+ <span class="p">(</span><span class="n">resolve</span> <span
class="n">any</span> <span class="n">conflicts</span><span class="p">,</span>
<span class="n">make</span> <span class="n">sure</span> <span
class="n">it</span> <span class="n">builds</span><span class="p">)</span>
+<span class="n">git</span> <span class="n">push</span> <span
class="o">-</span><span class="n">u</span> <span class="n">origin</span> <span
class="n">THRIFT</span><span class="o">-</span>9999 <span
class="o">--</span><span class="n">force</span>
+</pre></div>
+
+
+<h3 id="fix-a-bad-merge">Fix a bad merge<a class="headerlink"
href="#fix-a-bad-merge" title="Permanent link">¶</a></h3>
+<p>If your pull request contains commits that are not yours, then you should
use the following technique to fix the bad merge in your branch:</p>
+<div class="codehilite"><pre><span class="n">git</span> <span
class="n">checkout</span> <span class="n">master</span>
+<span class="n">git</span> <span class="n">pull</span> <span
class="n">upstream</span> <span class="n">master</span>
+<span class="n">git</span> <span class="n">checkout</span> <span
class="o">-</span><span class="n">b</span> <span class="n">THRIFT</span><span
class="o">-</span>9999<span class="o">-</span><span class="n">take</span><span
class="o">-</span>2
+<span class="n">git</span> <span class="n">cherry</span><span
class="o">-</span><span class="n">pick</span> <span class="p">...</span>
+ <span class="p">(</span><span class="n">pick</span> <span
class="n">only</span> <span class="n">your</span> <span
class="n">commits</span> <span class="n">from</span> <span
class="n">your</span> <span class="n">original</span> <span
class="n">pull</span> <span class="n">request</span> <span class="n">in</span>
<span class="n">ascending</span> <span class="n">chronological</span> <span
class="n">order</span><span class="p">)</span>
+<span class="n">squash</span> <span class="n">your</span> <span
class="n">changes</span> <span class="n">to</span> <span class="n">a</span>
<span class="n">single</span> <span class="n">commit</span> <span
class="k">if</span> <span class="n">there</span> <span class="n">is</span>
<span class="n">more</span> <span class="n">than</span> <span
class="n">one</span> <span class="p">(</span><span class="n">see</span> <span
class="n">above</span><span class="p">)</span>
+<span class="n">git</span> <span class="n">push</span> <span
class="o">-</span><span class="n">u</span> <span class="n">origin</span> <span
class="n">THRIFT</span><span class="o">-</span>9999<span
class="o">-</span><span class="n">take</span><span class="o">-</span>2<span
class="p">:</span><span class="n">THRIFT</span><span class="o">-</span>9999
+</pre></div>
+
+
+<p>This procedure will apply only your commits in order to the current master,
then you will squash them to a single commit, and then you force push your
local THRIFT-9999-take-2 into remote THRIFT-9999 which represents your pull
request, replacing all the commits with the new one.</p>
<p class='snippet_footer'>
This snippet was generated by Apache Thrift's <strong>source tree
docs</strong>:
<a
href="http://git-wip-us.apache.org/repos/asf?p=thrift.git;a=blob;f=CONTRIBUTING.md;hb=HEAD";</a>CONTRIBUTING.md</a>
