This is a note for myself on contributing to open source software on GitHub. Specifically on the the topic of making multiple pull requests from my own fork on a public repository.
Dislaimer: Everything here is based on my own understanding from multiple sources (stackoverflow, bitbucket tutorial and hub), it may not be the “right” way to do it.
I am using pysam as an example to illustrate the use of git feature branch workflow for creating multiple pull requests from a single fork/user.
On GitHub, every public repository can be forked. Forking a repository means cloning the repository and creating a copy that resides on the user’s own GitHub homepage.
For this pysam example, forking pysam from pysam-developers/pysam is going to create a pysam repository on wckdouglas/pysam.
Cloning repositories from GitHub to a local destination should be familiar to most GitHub users. This can be done by git clone git@github.com:wckdouglas/pysam.git.
It is suggested master branch should not be touched, every new feature should be added to it’s own isolated branch. This practice ensures every pull request is only adding one feature or fixing one issue at a time, and is better for the maintainer to review/merge the pull requests.
Suppose there are two new features (new_feature_1 and new_feature_2) that I want to add, it will require make two new branches:
git branch new_feature_1
git checkout new_feature_1
git branch new_feature_2
git checkout new_feature_2
Alternatively, it can be done in a single command:
git checkout -b new_feature_1
git checkout -b new_feature_2
checkout -b checks a branch out, or creates it if its not thereAfter making changes, branches can be push to GitHub repository by
git push origin new_feature_1
If the branch is pushed to GitHub, then a pull request can be made by clicking New pull request (blue box) from the chosen fork (red box).
So if I want to add two different features, the workflow will be:
git checkout -b new_feature_1
< ...make changes... >
git commit -am 'some message'
git push origin new_feature_1
Then, make a new branch from *master branch, and do the same thing again:
git branch new_feature_2 master
git checkout new_feature_2
< ...make changes... >
git commit -am 'some message'
git push origin new_feature_2
Git is magical, and this is mostly the reason why we don’t always do things right at the first time. As pysam is the first repository that I have made two pull requests before any of them was merged, I made a mistake where I fixed an issue on my master branch and made a pull request from my master branch. This was fine until I wanted to make a change to speed up a function in pysam, since any new commits and pushes on my master branch will automatically be added to the first pull requests that I made and will violate the rule: one pull request should only fix one thing.
Long story short, I fixed this by checking out the last commit before I made any changes on master branch, then started a new branch (speed_up_find_intron) based on this commit, and finally made a second pull request with this branch (speed_up_find_intron). But my first pull is still made from my master branch… Anyway, I hope anyone who read this post will not make the same mistake that I did.
git checkout <last commit before I amde changes> # revert to the initial state of the public repository
git checkout -b speed_up_find_intron # make a fresh branch that only add one feature
< ...make changes...>
git commit -am 'fixed a inefficient loop'
git push origin speed_up_find_intron # push this new branch to my own github repository
