Fork the SINGA Github repository to your own Github account.
Clone the repo (short for repository) from your Github
git clone https://github.com/<Github account>/singa.git git remote add upstream https://github.com/apache/singa.git
Create a new branch (e.g.,
fixbug-foo), work on it and commit your code.
git checkout dev git checkout -b feature-foo write your code git add <created/updated files> git commit
The commit message should include:
- A descriptive Title.
- A detailed description. If the commit is to fix a bug, the description should ideally include a short reproduction of the problem. For new features, it may include the motivation/purpose of this new feature.
If your branch has many small commits, you need to clean those commits via
git rebase -i <commit id>
You can squash and reword the commits.
When you are working on the code, the
devof SINGA may have been updated by others; In this case, you need to pull the latest dev
git checkout dev git pull upstream dev:dev
devbranch and push commits to your own Github account (the new branch). The rebase operation is to make the commit history clean. The following git instructors should be executed after committing the current work:
git checkout feature-foo git rebase dev git push origin feature-foo:feature-foo
The rebase command does the following steps: "This operation works by going to the common ancestor of the two branches (the one you’re on and the one you’re rebasing onto), getting the diff introduced by each commit of the branch you’re on, saving those diffs to temporary files, resetting the current branch to the same commit as the branch you are rebasing onto, and finally applying each change in turn." Therefore, after executing it, you will be still on the feature branch, but your own commit IDs/hashes are changed since the diffs are committed during rebase; and your branch now has the latest code from the dev branch and your own branch.
Open a pull request (PR) against the dev branch of apache/singa on Github website. If you want to inform other contributors who worked on the same files, you can find the file(s) on Github and click "Blame" to see a line-by-line annotation of who changed the code last. Then, you can add @username in the PR description to ping them immediately. Please state that the contribution is your original work and that you license the work to the project under the project's open source license. Further commits (e.g., bug fix) to your new branch will be added to this pull request automatically by Github.
Wait for committers to review the PR. During this time, the dev of SINGA may have been updated by others, and then you need to merge the latest dev to resolve conflicts. Some people rebase the PR onto the latest dev instead of merging. However, if other developers fetch this PR to add new features and then send PR, the rebase operation would introduce duplicate commits (with different hash) in the future PR. See The Golden Rule of Rebasing for the details of when to avoid using rebase. Another simple solution to update the PR (to fix conflicts or commit errors) is to checkout a new branch from the latest dev branch of Apache SINGAS repo; copy and paste the updated/added code; commit and send a new PR.
Committers can merge the pull requests (PRs) into the dev branch of the upstream repo. Before merging each PR, the committer should
- check the commit message (content and format)
- check the changes to existing code. API changes should be recorded
- check the Travis testing results for code/doc format and unit tests
There are two approaches to merge a pull request:
On Github. Follow the instructions to connect your Apache account with your Github account. After that you can directly merge PRs on GitHub.
To merge pull request https://github.com/apache/singa/pull/xxx via command line, the following instructions should be executed,
git clone https://github.com/apache/singa.git git remote add asf https://gitbox.apache.org/repos/asf/singa.git git fetch origin pull/xxx/head:prxxx git checkout dev git merge --no-ff prxxx git push asf dev:dev
Do not use rebase to merge the PR; and disable fast forward.