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

[dl...@apache.org]

Author: dlyubimov
Date: Wed May 28 00:05:09 2014
New Revision: 1597905

URL: http://svn.apache.org/r1597905
Log:
CMS commit to mahout by dlyubimov

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=1597905&r1=1597904&r2=1597905&view=diff
==============================================================================
--- mahout/site/mahout_cms/trunk/content/developers/github.mdtext (original)
+++ mahout/site/mahout_cms/trunk/content/developers/github.mdtext Wed May 28 00:05:09 2014
@@ -18,74 +18,85 @@ Notice:    Licensed to the Apache Softwa
 
 # Handling Github PRs #
 
+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.
 
+Otherwise, here's recommended procedure to resolve external github pull requests to apache/Mahout repository.
 
 ## How to create a PR (for contributers)
 
-Read \[[1]\]. 
+Create pull requests: \[[1]\]. 
 
 Pull requests are made to apache/mahout repository on Github. 
 
 ## Merging a PR and closing it (for committers) 
 
-Remember that pull requests are equivalent to a remote branch with potentially a multitude of commits. 
+Start with reading \[[2]\] (merging locally). 
+
+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 contributer's commits. In order to do that, as well as close the PR at the 
 same time, it is recommended to use **squash commits**.
 
-Read \[[2]\] (merging locally). Merging pull requests are equivalent to merging contributor's branch:
+Merging pull requests are equivalent to merging contributor's branch:
 
     git checkout master      # switch to local master branch
     git pull apache master   # fast-forward to current remote HEAD
     git pull --squash https://github.com/cuser/mahout cbranch  # merge to master 
 
 
-In this example we assume that contributor Github handle is "cuser" and the PR branch name is "cbranch" there. We also 
-assume that *apache* remote is configured as 
+In this example we assume that contributor Github handle is "cuser" and the PR branch name is "cbranch" there. 
+
+We also assume that *apache* remote is configured as 
 
     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. Also, it is not yet committed, even if 
-fast forward is possible, so you get chance to change things before committing.
+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.
 
-At this point 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 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 
+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 #ZZ**"
+
+where `ZZ` is the pull request number. Including "closes #ZZ" will close PR automatically. 
+More information here \[[3]\].
+
+Next, push to git-wip-us.a.o:
 
-    git commit -a
+    push apache master
 
-edit message to contain "MAHOUT-YYYY description **closes #ZZ**", where ZZ is the pull request number. 
-Including "closes #ZZ" will close PR automatically. More information \[[3]\].
+(this will require Apache handle credentials).
 
-   push apache master
+    
 
-(this will require credentials).
 
-Note on squashing: Since squash discards remote branch history, repeated PRs from the same remote branch are 
-difficult for merging. The workflow implies that every new PR starts with a new rebased branch. This is more 
-important for contributors to know, rather than for committers, because if new PR is not mergeable, github
-would warn to begin with. Anyway, watch for dupe PRs (based on same source branches). This is a bad practice.
+    Note on squashing: Since squash discards remote branch history, repeated PRs from the same remote branch are 
+    difficult for merging. The workflow implies that every new PR starts with a new rebased branch. This is more 
+    important for contributors to know, rather than for committers, because if new PR is not mergeable, github
+    would warn to begin with. Anyway, watch for dupe PRs (based on same source branches). This is a bad practice.
      
-## Closing a PR without committing 
+## Closing a PR without committing (for committers)
 
-When we want to reject a PR (close without committing), just do the following commit on master's HEAD 
+When we want to reject a PR (close without committing), we can just issue an empty commit on master's HEAD 
 *without merging the PR*: 
 
     git commit --allow-empty -m "closes #ZZ *Won't fix*"
     git push apache master
 
-that should close PR without merging and any code modifications in the master repository.
+that should close PR `ZZ` on github mirror without merging and any code modifications in the master repository.
 
 ## Apache/github integration features 
 
-Read \[[4]\]. Issue handles mentioned in comments and PR name should post to mailing lists and Jira.
+Read \[[4]\]. Comments (and PRs?) with Mahout issue handles should post to mailing lists and Jira.
 
 
 [1]: https://help.github.com/articles/creating-a-pull-request
 [2]: https://help.github.com/articles/merging-a-pull-request#merging-locally
 [3]: https://help.github.com/articles/closing-issues-via-commit-messages
-[4]: https://blogs.apache.org/infra/entry/improved_integration_between_apache_and
+[4]: https://blogs.apache.org/infra/entry/improved_integration_between_apache_and
\ No newline at end of file