Split 'Git setup' for contributors and committers closes apache/incubator-rocketmq-site#3
Project: http://git-wip-us.apache.org/repos/asf/incubator-rocketmq-site/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-rocketmq-site/commit/539112ef Tree: http://git-wip-us.apache.org/repos/asf/incubator-rocketmq-site/tree/539112ef Diff: http://git-wip-us.apache.org/repos/asf/incubator-rocketmq-site/diff/539112ef Branch: refs/heads/asf-site Commit: 539112ef6683ac1bdd953478088846b1bc8ddaf5 Parents: 0dcf510 Author: shroman <[email protected]> Authored: Fri Jan 6 13:31:45 2017 +0800 Committer: yukon <[email protected]> Committed: Fri Jan 6 13:31:45 2017 +0800 ---------------------------------------------------------------------- _docs/06-best-practice-pull-request.md | 46 ++++++++++++++++++++++------- 1 file changed, 35 insertions(+), 11 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-rocketmq-site/blob/539112ef/_docs/06-best-practice-pull-request.md ---------------------------------------------------------------------- diff --git a/_docs/06-best-practice-pull-request.md b/_docs/06-best-practice-pull-request.md index cda50d0..d9972ef 100644 --- a/_docs/06-best-practice-pull-request.md +++ b/_docs/06-best-practice-pull-request.md @@ -4,23 +4,43 @@ permalink: /docs/pull-request/ modified: 2016-12-24T15:01:43-04:00 --- -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. +This page guides you through Git setup and contribution process. {% include toc %} # Git setup for Contributors -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/incubator-rocketmq 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. +First of all, fork githubâs `apache/incubator-rocketmq` to your own account on github and clone it as follows, -To attach to the apache git repo do the following: + git clone https://github.com/<your_github_name>/incubator-rocketmq.git + +Cloning this locally will set up `origin` to point to your remote fork on github as the default remote. +Now you can create your pull requests. + +You will need to update a local master sometimes (to merge to your development branches sometimes). +For this, you have to add remote for RocketMQ mirror as follows, + + git remote add upstream https://github.com/apache/incubator-rocketmq.git + +and update your local master via `git fetch` followed by `git rebase`, for instance, as follows + + git fetch upstream master + git rebase upstream/master + +# Git setup for Committers +In addition to contributors' configurations, committers will have to attach the apache git repo: git remote add apache https://git-wip-us.apache.org/repos/asf/incubator-rocketmq.git -To check your remote setup -git remote -v -you should see something like this: +To check your remote setup, issue + + git remote -v + +You should see something like this: - origin https://github.com/your-github-id/incubator-rocketmq.git (fetch) - origin https://github.com/your-github-id/incubator-rocketmq.git (push) + origin https://github.com/<your_github_name>/incubator-rocketmq.git (fetch) + origin https://github.com/<your_github_name>/incubator-rocketmq.git (push) + upstream https://github.com/apache/incubator-rocketmq.git (fetch) + upstream https://github.com/apache/incubator-rocketmq.git (push) apache https://git-wip-us.apache.org/repos/asf/incubator-rocketmq.git (fetch) apache https://git-wip-us.apache.org/repos/asf/incubator-rocketmq.git (push) @@ -28,6 +48,8 @@ Now if you want to experiment with a branch everything, by default, points to yo git checkout -b ROCKETMQ-xxxx #xxxx typically is a JIRA ticket number +_To guarantee code quality of the master branch, all but minor changes should go through pull requests reviewed by peer committers._ + # Do some work on the branch git commit -a -m "doing some work" @@ -47,13 +69,15 @@ Push your branch to Github: 2. Click the green "Compare, review, and create pull request" button.You can edit the to and from for the PR if it isn't correct. The "base fork" should be apache/incubator-rocketmq 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 ROCKETMQ-xxxx branch. 3. Click the "Create pull request" button and name the request "ROCKETMQ-xxxx" all caps. This will connect the comments of the PR to the mailing list and JIRA comments. 4. From now on the PR lives on github's apache/incubator-rocketmq. You use the commenting UI there. -5. 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. +5. 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. 6. When you are satisfied and want to push it to Apache's remote repo proceed with Merging a PR # How to create a PR (contributors) Create pull requests: [GitHub PR docs](https://help.github.com/articles/creating-a-pull-request/). -Pull requests are made to apache/incubator-rocketmq 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. +_Make sure you follow_ [Coding Guidelines]{http://rocketmq.apache.org/docs/code-guidelines/} _before you create a pull request._ + +Pull requests are made to `apache/incubator-rocketmq` 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. # Merging a PR (yours or contributors) Start with reading [GitHub PR merging locally](https://help.github.com/articles/checking-out-pull-requests-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 contributor's commits. In order to do that, as well as close the PR at the same time, it is recommended to use squash commits. @@ -63,7 +87,7 @@ Merging pull requests are equivalent to a "pull" of a contributor's branch: git pull apache master # fast-forward to current remote HEAD git pull --squash https://github.com/cuser/incubator-rocketmq.git ROCKETMQ-xxxx # merge to master ---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 --squash option. In this example we assume that the contributor's Github handle is "cuser" and the PR branch name is "ROCKETMQ-xxxx". Next, resolve conflicts, if any, or ask a contributor to rebase on top of master, if PR went out of sync. +`--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 `--squash` option. In this example we assume that the contributor's Github handle is "cuser" and the PR branch name is "ROCKETMQ-xxxx". Next, resolve conflicts, if any, or ask a contributor to rebase on top of master, if PR went out of sync. 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.
