This page guides you through Git setup and contribution process.
{% include toc %}
First of all, fork github’s apache/rocketmq to your own account on github and clone it as follows,
git clone https://github.com/<your_github_name>/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 apache https://github.com/apache/rocketmq.git
and update your local master via git fetch followed by git rebase, for instance:
git fetch apache master git rebase apache/master
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.
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/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/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 issue comments.
From now on the PR lives on github's apache/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 Github issue and the mailing list.
When you are satisfied and want to push it to Apache's remote repo, you can merge this PR.
Before you create a pull request, make sure
For information about creating pull requests, please check GitHub PR docs.
Pull requests are made to apache/rocketmq repository on Github. In the Github UI you should pick the develop 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.
Each pull request should follow the checklist to help us incorporate your contribution quickly and easily.
Remember use - [x] mark an item finished in the check list and there is a demo pull request can be your reference.
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/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/rocketmq#ZZ"
ROCKETMQ-XXXX is all capitalized and ZZ is the pull request number on apache/rocketmq repository. Including “closes apache/rocketmq#ZZ” will close the PR automatically. More information can be found here GitHub PR closing docs.. Next, push to apache:
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).
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/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.