This page guides you through Git setup and contribution process.
Git setup for Contributors
First of all, fork github’s
apache/incubator-rocketmq to your own account on github and clone it as follows,
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). 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:
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, issue
git remote -v
You should see something like this:
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)
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.
git checkout -b ROCKETMQ-xxxx #xxxx typically is a JIRA ticket number
To ensure the 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" git push origin ROCKETMQ-xxxx # notice pushing to **origin** not **apache**
Once you are ready to commit to the apache remote you can merge and push them directly, otherwise always create a PR.
How to create a PR (committers)
Push your branch to Github:
git checkout ROCKETMQ-xxxx git push origin ROCKETMQ-xxxx
Go to your ROCKETMQ-xxxx branch on Github. Since you forked it from Github’s apache/incubator-rocketmq. By default all PR will go to apache/master.
- 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 with one of the committers on the list. The “base” will be master. Don’t submit a PR to any other branches unless permitted by branch owner. The “head fork” will be your forked repo and the “compare” will be your ROCKETMQ-xxxx branch.
- 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.
- From now on the PR lives on github’s apache/incubator-rocketmq. You can use the commenting UI there.
- If you are looking for a review or wanting to share with someone else please write a note in the comments and 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.
- When you are satisfied and want to push it to Apache’s remote repo, you can merge this PR.
How to create a PR (contributors)
Before you create a pull request, make sure
- A corresponding JIRA issue is created and has a clear problem description.
- Make sure you follow Coding Guidelines.
- You have unit tests for everything you are about to commit.
For information about creating pull requests, please check GitHub PR docs.
Pull requests are made to
apache/incubator-rocketmq repository on Github.
In the Github UI you should pick the master branch as target of the PR.
You pull request will be reviewed and commented by committers, and issues can be discussed. When all reviewers are positive on the pull request, it will be merged.
Check List for a PR
Each pull request should follow this checklist to help us incorporate your contribution quickly and easily:
- [x] Make sure there is a [JIRA issue](https://issues.apache.org/jira/projects/ROCKETMQ/issues/) filed for the change (usually before you start working on it). Trivial changes like typos do not require a JIRA issue. Your pull request should address just this issue, without pulling in other changes - one PR resolves one issue. - [ ] Format the pull request title like `[ROCKETMQ-XXX] Fix UnknownException when host config not exist`. Each commit in the pull request should have a meaningful subject line and body. - [ ] Write a pull request description that is detailed enough to understand what the pull request does, how, and why. - [ ] Write necessary unit-test to verify your logic correction, more mock a little better when cross module dependency exist. If the new feature or significant change is committed, please remember to add integration-test in [test module](https://github.com/apache/incubator-rocketmq/tree/master/test). - [ ] Run `mvn -B clean apache-rat:check findbugs:findbugs checkstyle:checkstyle` to make sure basic checks pass. Run `mvn clean install -DskipITs` to make sure unit-test pass. Run `mvn clean test-compile failsafe:integration-test` to make sure integration-test pass. - [ ] If this contribution is large, please file an [Apache Individual Contributor License Agreement](http://www.apache.org/licenses/#clas).
- [x] mark an item finished in the check list and there is a demo pull request can be your reference.
Merging a PR (yours or contributors)
Start with reading GitHub PR 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 contributor’s commits. In order to do that, as well as to close the PR at the same time, it is recommended to use squash commits. Merging pull requests are equivalent to a “pull” of a 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/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. Please refer to 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 all conflicts, 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 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.
git checkout master # switch to local master branch git pull apache master # fast-forward to current remote HEAD git merge --squash ROCKETMQ-xxxx
Please run regular patch checks, build with tests enabled, and change CHANGELOG whenever needed. If all requirements are met, you can commit the squashed request using:
git commit --author="contributor_name <contributor_email>" -a -m "ROCKETMQ-XXXX description closes apache/incubator-rocketmq#ZZ"
ROCKETMQ-XXXX is all capitalized and ZZ is the pull request number on apache/incubator-rocketmq repository. Including “closes apache/incubator-rocketmq#ZZ” will close the PR automatically. More information can be found here GitHub PR closing docs.. Next, push to git-wip-us.apache.org:
git push apache master
(this will require Apache handle credentials). The PR, once pushed, will get mirrored to github. To update your github version push there too:
git push origin master
Note on squashing: Since squash discards remote branch history, repeated PRs from the same remote branch are difficult to be merged. 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 at the start. Please watch for dupe PRs (based on same source branches).
Closing a PR without committing (for committers)
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 "ROCKETMQ-XXXX closes apache/incubator-rocketmq#ZZ *Won't fix*" git push apache master
that should close PR ZZ on github mirror without merging and any code modifications in the master repository.more detail please refer to RocketMQ PR https://github.com/apache/incubator-rocketmq/pull/15
Apache/github integration features
Read infra blog. Comments and PRs with RocketMQ issue handles should post to mailing lists and JIRA. RocketMQ issue handles must in the form ROCKETMQ-YYYYY (all capitals). Usually it makes sense to file a JIRA issue first, and then create a PR with description
Avoiding accidentally committing private branches to the ASF repo
It’s dangerous —especially when using IDEs— to accidentally commit changes to the ASF repo, be directed to the trunk, branch-2, other standard branch on which you are developing, or to a private branch you had intended to keep on github (or a private repo).
Committers can avoid this by setting the directory in which they develop code to read only access to the ASF repository on github. A separate directory should also be set up with write access to the ASF repository as well as read access to your other repositories. Merging operations and push backs to the ASF repo are done from this directory —so it will be immune to all local changes.
If you accidentally committed a patch to an ASF branch, do not attempt to roll back the branch and force out a new update. Simply commit and push out a new patch revoking the change.
If you do accidentally committed a branch to the ASF repo, the infrastructure team can delete it —but they cannot stop it propagating to github and potentially being visible. Please avoid this.