svn commit: r1600722 - /mahout/site/mahout_cms/trunk/content/developers/github.mdtext

[pa...@apache.org]

Author: pat
Date: Thu Jun  5 18:41:10 2014
New Revision: 1600722

URL: http://svn.apache.org/r1600722
Log:
trying first cwiki edit with some explanation of how to setup for github integration.

Modified:
    mahout/site/mahout_cms/trunk/content/developers/github.mdtext

Modified: mahout/site/mahout_cms/trunk/content/developers/github.mdtext
URL: http://svn.apache.org/viewvc/mahout/site/mahout_cms/trunk/content/developers/github.mdtext?rev=1600722&r1=1600721&r2=1600722&view=diff
==============================================================================
--- mahout/site/mahout_cms/trunk/content/developers/github.mdtext (original)
+++ mahout/site/mahout_cms/trunk/content/developers/github.mdtext Thu Jun  5 18:41:10 2014
@@ -27,7 +27,31 @@ Otherwise, here's recommended procedure 
 
 Create pull requests: \[[1]\]. 
 
-Pull requests are made to apache/mahout repository on Github. 
+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.
+
+##Git setup for Committers
+
+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.
+
+To attach to the apache git repo do the following:
+
+    git remote add apache https://git-wip-us.apache.org/repos/asf/mahout.git
+
+Now if you want to experiment with a branch do the following:
+
+    git checkout -b mahout-xxxx #xxxx typically is a Jira ticket number
+    #do some work on the branch
+    git commit -a -m "MAHOUT-XXXX doing some work"
+    git push origin mahout-xxxx #notice pushing to 'origin' not 'apache'
+
+Once you are ready to commit to the apache master you can push them directly **if they are very small changes**. Do the following:
+
+    git checkout master
+    git merge mahout-xxxx
+    # check build and tests
+    git push apache master #this pushes all changes you just merged
+
+For most non-trivial work it's best to use a PR so go to your github account, pick the branch you want to push and create a pull request. Github will ask for the "base fork:" this should be github's apache/mahout , and the "base:" should be "master". This will create a pull request for review on gtihub. Once the review is complete proceed to merging below.
 
 ## Merging a PR and closing it (for committers) 
 
@@ -44,25 +68,30 @@ Merging pull requests are equivalent to 
     git pull apache master   # fast-forward to current remote HEAD
     git pull --squash https://github.com/cuser/mahout cbranch  # merge to master 
 
+Squash pull 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 `--squash` option.
 
-In this example we assume that contributor Github handle is "cuser" and the PR branch name is "cbranch" there. 
+In this example we assume that the contributor's or committer's Github handle is "cuser" and the PR branch name is "cbranch" there. 
 
-We also assume that *apache* remote is configured as 
+We also assume that *apache* remote is configured as stated above. To check do the following
 
-    apache  https://git-wip-us.apache.org/repos/asf/mahout.git (fetch)
-    apache  https://git-wip-us.apache.org/repos/asf/mahout.git (push)
+    git remote -v
 
+you should see something like this:
+
+    origin    https://github.com/cuser/mahout.git (fetch)
+    origin    https://github.com/cuser/mahout.git (push)
+    apache    https://git-wip-us.apache.org/repos/asf/mahout.git (fetch)
+    apache    https://git-wip-us.apache.org/repos/asf/mahout.git (push)
 
-Squash pull 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 `--squash` option.
 
-Next, resolve conflicts, if any, or ask contributor to rebase on top of master, if PR went out of sync.
+Next, resolve conflicts, if any, or ask a contributor to rebase on top of master, if PR went out of sync.
 
 Also run regular patch checks and change CHANGELOG.
 
 Suppose everything is fine, you now can commit the squashed request along the lines
 
-    git commit -a -m "MAHOUT-YYYY description (cuser via ssc) closes apache/mahout#ZZ"
+    git commit -a -m "MAHOUT-YYYY description (cuser via your-apache-id) closes apache/mahout#ZZ"
 
 where `ZZ` is the pull request number on apache/mahout repository. Including "closes apache/mahout#ZZ" 
 will close PR automatically. More information is found here \[[3]\].
@@ -73,6 +102,10 @@ Next, push to git-wip-us.a.o:
 
 (this will require Apache handle credentials).
 
+The PR, once pushed, will get mirrored to github. To update your github version push there too:
+
+    push origin master
+