Author: buildbot
Date: Mon Jun 23 23:02:53 2014
New Revision: 913436
Log:
Staging update by buildbot for mahout
Modified:
websites/staging/mahout/trunk/content/ (props changed)
websites/staging/mahout/trunk/content/developers/github.html
Propchange: websites/staging/mahout/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Mon Jun 23 23:02:53 2014
@@ -1 +1 @@
-1604655
+1604954
Modified: websites/staging/mahout/trunk/content/developers/github.html
==============================================================================
--- websites/staging/mahout/trunk/content/developers/github.html (original)
+++ websites/staging/mahout/trunk/content/developers/github.html Mon Jun 23
23:02:53 2014
@@ -242,15 +242,17 @@
<div id="content-wrap" class="clearfix">
<div id="main">
- <h1 id="handling-github-prs">Handling Github PRs</h1>
-<p>When we don't want to use Github's PR collaboration tools, we always can
just commit a patch directly by
-pushing it to https://git-wip-us.apache.org/repos/asf/mahout.git.</p>
-<p>Otherwise, here's recommended procedure to resolve external github pull
requests to apache/Mahout repository.</p>
-<h2 id="how-to-create-a-pr-for-contributors">How to create a PR (for
contributors)</h2>
-<p>Create pull requests: [<a
href="https://help.github.com/articles/creating-a-pull-request";>1</a>]. </p>
-<p>Pull requests are made to apache/mahout repository on Github. In the Github
UI you should pick the master branch to target the PR. This will be reviewed
and commented on so the merge is not automatic. This can be used for discussing
a contributions in progress but the committer should make sure to state that it
is not intended for merging with master in the comments.</p>
+ <h1 id="github-setup-and-pull-requests-prs">Github Setup and Pull Requests
(PRs)</h1>
+<p>There are several ways to setup Git for committers and contributors.
Contributors can safely setup
+Git any way they choose but committers should take extra care since they can
push new commits to the master at
+Apache and various policies there make backing out mistakes problematic.
Therefore all but very small changes should
+go through a PR, even for committers. To keep the commit history clean take
note of the use of --squash below
+when merging into apache/master.</p>
<h2 id="git-setup-for-committers">Git setup for Committers</h2>
-<p>You will want to fork github's apache/mahout to your own account, this will
allow Pull Requests of your own. Cloning this fork locally will set up "origin"
to point to your remote fork on github as the default remote. So if you perform
"git push origin master" it will go to github.</p>
+<p>This describes setup for one local repo and two remotes. It allows you to
push the code on your machine to either your Github repo or to
git-wip-us.apache.org.
+You will want to fork github's apache/mahout to your own account on github,
this will enable Pull Requests of your own.
+Cloning this fork locally will set up "origin" to point to your remote fork on
github as the default remote.
+So if you perform "git push origin master" it will go to github.</p>
<p>To attach to the apache git repo do the following:</p>
<div class="codehilite"><pre><span class="n">git</span> <span
class="n">remote</span> <span class="n">add</span> <span
class="n">apache</span> <span class="n">https</span><span
class="p">:</span><span class="o">//</span><span class="n">git</span><span
class="o">-</span><span class="n">wip</span><span class="o">-</span><span
class="n">us</span><span class="p">.</span><span class="n">apache</span><span
class="p">.</span><span class="n">org</span><span class="o">/</span><span
class="n">repos</span><span class="o">/</span><span class="n">asf</span><span
class="o">/</span><span class="n">mahout</span><span class="p">.</span><span
class="n">git</span>
</pre></div>
@@ -272,54 +274,74 @@ pushing it to https://git-wip-us.apache.
<p>Now if you want to experiment with a branch everything, by default, points
to your github account because 'origin' is default. You can work as normal
using only github until you are ready to merge with the apache remote. Some
conventions will integrate with Apache Jira ticket numbers.</p>
<div class="codehilite"><pre><span class="n">git</span> <span
class="n">checkout</span> <span class="o">-</span><span class="n">b</span>
<span class="n">mahout</span><span class="o">-</span><span
class="n">xxxx</span> #<span class="n">xxxx</span> <span
class="n">typically</span> <span class="n">is</span> <span class="n">a</span>
<span class="n">Jira</span> <span class="n">ticket</span> <span
class="n">number</span>
#<span class="n">do</span> <span class="n">some</span> <span
class="n">work</span> <span class="n">on</span> <span class="n">the</span>
<span class="n">branch</span>
-<span class="n">git</span> <span class="n">commit</span> <span
class="o">-</span><span class="n">a</span> <span class="o">-</span><span
class="n">m</span> "<span class="n">MAHOUT</span><span
class="o">-</span><span class="n">XXXX</span> <span class="n">doing</span>
<span class="n">some</span> <span class="n">work</span>"
-<span class="n">git</span> <span class="n">push</span> <span
class="n">origin</span> <span class="n">mahout</span><span
class="o">-</span><span class="n">xxxx</span> # <span class="n">notice</span>
<span class="n">pushing</span> <span class="n">to</span> <span
class="s">'origin'</span> <span class="n">not</span> <span
class="s">'apache'</span>
+<span class="n">git</span> <span class="n">commit</span> <span
class="o">-</span><span class="n">a</span> <span class="o">-</span><span
class="n">m</span> "<span class="n">doing</span> <span
class="n">some</span> <span class="n">work</span>"
+<span class="n">git</span> <span class="n">push</span> <span
class="n">origin</span> <span class="n">mahout</span><span
class="o">-</span><span class="n">xxxx</span> # <span class="n">notice</span>
<span class="n">pushing</span> <span class="n">to</span> <span
class="o">**</span><span class="n">origin</span><span class="o">**</span> <span
class="n">not</span> <span class="o">**</span><span
class="n">apache</span><span class="o">**</span>
</pre></div>
-<p>Once you are ready to commit to the apache master you can push them
directly:</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">apache</span> <span class="n">master</span> # <span
class="n">may</span> <span class="n">have</span> <span class="n">to</span>
<span class="nb">fix</span> <span class="n">merge</span> <span
class="n">conflicts</span>
-<span class="n">git</span> <span class="n">merge</span> <span
class="n">mahout</span><span class="o">-</span><span class="n">xxxx</span>
-# <span class="n">check</span> <span class="n">build</span> <span
class="n">and</span> <span class="n">tests</span>
-<span class="n">git</span> <span class="n">push</span> <span
class="n">apache</span> <span class="n">master</span> #<span
class="n">this</span> <span class="n">pushes</span> <span class="n">all</span>
<span class="n">changes</span> <span class="n">you</span> <span
class="n">just</span> <span class="n">merged</span> <span class="n">to</span>
<span class="n">the</span> <span class="n">apache</span> <span
class="n">git</span> <span class="n">remote</span> <span class="n">repo</span>
+<p>Once you are ready to commit to the apache remote you can merge and push
them directly or better yet create a PR. </p>
+<h2 id="how-to-create-a-pr-committers">How to create a PR (committers)</h2>
+<p>Push your branch to Github:</p>
+<div class="codehilite"><pre><span class="n">git</span> <span
class="n">checkout</span> <span class="n">mahout</span><span
class="o">-</span><span class="n">xxxx</span>
+<span class="n">git</span> <span class="n">push</span> <span
class="n">origin</span> <span class="n">mahout</span><span
class="o">-</span><span class="n">xxxx</span>
</pre></div>
-<p>Since PRs reference a specific user's branch they may be used by committers
to collaborate with others or
-to get reviews before pushing to apache. Creating a PR only establishes a
place to review, you will have to
-merge your branch as above to get it into apache/master.</p>
-<h2 id="merging-a-contributors-pr-and-closing-it-for-committers">Merging a
contributor's PR and closing it (for committers)</h2>
+<p>Go to your mahout-xxxx branch on Github. Since you forked it from Github's
apache/mahout it will default
+any PR to go to apache/master. </p>
+<ul>
+<li>Click the green "Compare, review, and create pull request" button. </li>
+<li>You can edit the to and from for the PR if it isn't correct. The "base
fork" should be apache/mahout unless you are collaborating
+separately with one of the committers on the list. The "base" will be master.
Don't submit a PR to one of the other
+branches unless you know what you are doing. The "head fork" will be your
forked repo and the "compare" will be
+your mahout-xxxx branch. </li>
+<li>Click the "Create pull request" button and name the request "MAHOUT-XXXX"
all caps.
+This will connect the comments of the PR to the mailing list and Jira
comments.</li>
+<li>From now on the PR lives on github's apache/mahout. You use the commenting
UI there. </li>
+<li>If you are looking for a review or sharing with someone else say so in the
comments but don't worry about
+automated merging of your PR--you will have to do that later. The PR is tied
to your branch so you can respond to
+comments, make fixes, and commit them from your local repo. They will appear
on the PR page and be mirrored to Jira
+and the mailing list. </li>
+</ul>
+<p>When you are satisfied and want to push it to Apache's remote repo proceed
with <strong>Merging a PR</strong></p>
+<h2 id="how-to-create-a-pr-contributors">How to create a PR (contributors)</h2>
+<p>Create pull requests: [<a
href="https://help.github.com/articles/creating-a-pull-request";>1</a>]. </p>
+<p>Pull requests are made to apache/mahout repository on Github. In the Github
UI you should pick the master
+branch to target the PR as described for committers. This will be reviewed and
commented on so the merge is
+not automatic. This can be used for discussing a contributions in progress.</p>
+<h2 id="merging-a-pr-yours-or-contributors">Merging a PR (yours or
contributors)</h2>
<p>Start with reading [<a
href="https://help.github.com/articles/merging-a-pull-request#merging-locally";>2</a>]
(merging locally). </p>
<p>Remember that pull requests are equivalent to a remote github branch with
potentially a multitude of commits.
In this case it is recommended to squash remote commit history to have one
commit per issue, rather
than merging in a multitude of contributor's commits. In order to do that, as
well as close the PR at the
same time, it is recommended to use <strong>squash commits</strong>.</p>
-<p>Merging pull requests are equivalent to merging contributor's branch:</p>
+<p>Merging pull requests are equivalent to a "pull" of a contributor's
branch:</p>
<div class="codehilite"><pre><span class="n">git</span> <span
class="n">checkout</span> <span class="n">master</span> # <span
class="k">switch</span> <span class="n">to</span> <span class="n">local</span>
<span class="n">master</span> <span class="n">branch</span>
<span class="n">git</span> <span class="n">pull</span> <span
class="n">apache</span> <span class="n">master</span> # <span
class="n">fast</span><span class="o">-</span><span class="n">forward</span>
<span class="n">to</span> <span class="n">current</span> <span
class="n">remote</span> <span class="n">HEAD</span>
<span class="n">git</span> <span class="n">pull</span> <span
class="o">--</span><span class="n">squash</span> <span
class="n">https</span><span class="p">:</span><span class="o">//</span><span
class="n">github</span><span class="p">.</span><span class="n">com</span><span
class="o">/</span><span class="n">cuser</span><span class="o">/</span><span
class="n">mahout</span> <span class="n">cbranch</span> # <span
class="n">merge</span> <span class="n">to</span> <span class="n">master</span>
</pre></div>
-<p>If you are ready to merge your own (committer's) PR you probably only need
to merge, since you have a local copy that you've been working on. This is the
branch that you used to create the PR.</p>
+<p>--squash ensures all PR history is squashed into single commit, and allows
committer to use his/her own
+message. Read git help for merge or pull for more information about
<code>--squash</code> option. In this example we
+assume that the contributor's Github handle is "cuser" and the PR branch name
is "cbranch".
+Next, resolve conflicts, if any, or ask a contributor to rebase on top of
master, if PR went out of sync.</p>
+<p>If you are ready to merge your own (committer's) PR you probably only need
to merge (not pull), since you have a local copy
+that you've been working on. This is the branch that you used to create the
PR.</p>
<div class="codehilite"><pre><span class="n">git</span> <span
class="n">checkout</span> <span class="n">master</span> # <span
class="k">switch</span> <span class="n">to</span> <span class="n">local</span>
<span class="n">master</span> <span class="n">branch</span>
<span class="n">git</span> <span class="n">pull</span> <span
class="n">apache</span> <span class="n">master</span> # <span
class="n">fast</span><span class="o">-</span><span class="n">forward</span>
<span class="n">to</span> <span class="n">current</span> <span
class="n">remote</span> <span class="n">HEAD</span>
-<span class="n">git</span> <span class="n">merge</span> <span
class="o">--</span><span class="n">squash</span> <span class="n">cbranch</span>
# <span class="n">cbranch</span> <span class="n">here</span> <span
class="n">is</span> <span class="n">probably</span> <span
class="n">named</span> <span class="n">mahout</span><span
class="o">-</span><span class="n">xxxx</span> <span class="k">for</span> <span
class="n">a</span> <span class="n">Jira</span> <span class="n">ticket</span>
+<span class="n">git</span> <span class="n">merge</span> <span
class="o">--</span><span class="n">squash</span> <span
class="n">mahout</span><span class="o">-</span><span class="n">xxxx</span>
</pre></div>
-<p>--squash ensures all PR history is squashed into single commit, and allows
committer to use his/her own
-message. Read git help for merge or pull for more information about
<code>--squash</code> option. In this example we assume that the contributor's
Github handle is "cuser" and the PR branch name is "cbranch".
-Next, resolve conflicts, if any, or ask a contributor to rebase on top of
master, if PR went out of sync.</p>
<p>Remember to run regular patch checks, build with tests enabled, and change
CHANGELOG.</p>
<p>If everything is fine, you now can commit the squashed request along the
lines</p>
-<div class="codehilite"><pre><span class="n">git</span> <span
class="n">commit</span> <span class="o">-</span><span class="n">a</span> <span
class="o">-</span><span class="n">m</span> "<span
class="n">MAHOUT</span><span class="o">-</span><span class="n">YYYY</span>
<span class="n">description</span> <span class="p">(</span><span
class="n">cuser</span> <span class="n">via</span> <span
class="n">your</span><span class="o">-</span><span class="n">apache</span><span
class="o">-</span><span class="n">id</span><span class="p">)</span> <span
class="n">closes</span> <span class="n">apache</span><span
class="o">/</span><span class="n">mahout</span>#<span class="n">ZZ</span>"
+<div class="codehilite"><pre><span class="n">git</span> <span
class="n">commit</span> <span class="o">-</span><span class="n">a</span> <span
class="o">-</span><span class="n">m</span> "<span
class="n">MAHOUT</span><span class="o">-</span><span class="n">XXXX</span>
<span class="n">description</span> <span class="p">(</span><span
class="n">cuser</span> <span class="n">via</span> <span
class="n">your</span><span class="o">-</span><span class="n">apache</span><span
class="o">-</span><span class="n">id</span><span class="p">)</span> <span
class="n">closes</span> <span class="n">apache</span><span
class="o">/</span><span class="n">mahout</span>#<span class="n">ZZ</span>"
</pre></div>
-<p>where <code>ZZ</code> is the pull request number on apache/mahout
repository. Including "closes apache/mahout#ZZ"
-will close PR automatically. More information is found here [<a
href="https://help.github.com/articles/closing-issues-via-commit-messages";>3</a>].</p>
+<p>MAHOUT-XXXX is all caps and where <code>ZZ</code> is the pull request
number on apache/mahout repository. Including
+"closes apache/mahout#ZZ" will close the PR automatically. More information is
found here [<a
href="https://help.github.com/articles/closing-issues-via-commit-messages";>3</a>].</p>
<p>Next, push to git-wip-us.a.o:</p>
<div class="codehilite"><pre><span class="n">push</span> <span
class="n">apache</span> <span class="n">master</span>
</pre></div>
