Introduction
Well, they say GitHub is a social-media site for programmers. It provides a way of collaboration and contribution for programmers via pull request. If you are just using GitHub to download source code, you are not using it to the fullest potential. I often have users message/email me about some small fix they did for my libraries and expect me to merge their fix manually. On the other hand, if they did a pull request, I could have it merged automatically after a code review. In this tip, I am going to show how to do a pull request on my simplebinstream library on GitHub. The source code owner and contributor are 2 accounts controlled by me.
Contributor Steps
Go to the repo you are interested to contribute. Fork the repository.
Forking can take some time to complete if the repository is huge.
Next, open up a command prompt and clone the repository you just forked.
D:\Github>git clone https://github.com/ZodiacAZ/simplebinstream.git
Cloning into 'simplebinstream'...
remote: Counting objects: 150, done.
remote: Compressing objects: 100% (5/5), done.
Receiving objects: 100% (150/150) 1 (delta 0), pack-reused 145Receiving objects: 99% (149/150)
ts: 100% (150/150), 36.07 KiB | 0 bytes/s, done.
Resolving deltas: 100% (97/97), done.
Checking connectivity... done.
Switch to the development branch. The development branch in our case is master. So we need not do any switching. Some repository can have other development branch name such as develop: They only merge develop into master after changes are tested and stable.
The next step is to create a new branch (called fix_endian) based on development branch. Note: It has to be a new branch. You cannot make your modification on the same branch as origin. Your new branch can have any name as long as it does not clash with any existing branch.
D:\Github>git checkout -b fix_endian
Make our modification on the new branch. Then we commit and push to our repository.
D:\Github\simplebinstream>git status
On branch fix_endian
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)
modified: TestBinStream/SimpleBinStream.h
modified: TestBinStream/TestBinStream.cpp
no changes added to commit (use "git add" and/or "git commit -a")
D:\Github\simplebinstream>git add TestBinStream/SimpleBinStream.h
D:\Github\simplebinstream>git add TestBinStream/TestBinStream.cpp
D:\Github\simplebinstream>git status
On branch fix_endian
Changes to be committed:
(use "git reset HEAD <file>..." to unstage)
modified: TestBinStream/SimpleBinStream.h
modified: TestBinStream/TestBinStream.cpp
D:\Github\simplebinstream>git commit -m "Fix endian"
[fix_endian 0f19491] Fix endian
2 files changed, 51 insertions(+), 19 deletions(-)
D:\Github\simplebinstream>git push origin fix_endian
Fatal: HttpRequestException encountered.
Username for 'https://github.com': ZodiacAZ
Password for 'https://ZodiacAZ@github.com':
Counting objects: 5, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (5/5), done.
Writing objects: 100% (5/5), 796 bytes | 0 bytes/s, done.
Total 5 (delta 4), reused 0 (delta 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
To https://github.com/ZodiacAZ/simplebinstream.git
* [new branch] fix_endian -> fix_endian
We will go to our GitHub repo webpage and switch to our branch (fix_endian) from the master branch.
The button "Compare and pull request" will appear and click that.
It will bring us to this page and fill in the title and message. You can only allow to create the pull request when GitHub verifies there is no conflict. Conflict can happen if the owner already pushes some code whilst you do your modifications. If this is the case, you have to pull the latest source code and fix the conflict and commit and push the code again. Click the "Create pull request" button and your job is done. Now we can only wait patiently for the owner to review and merge our fix.
Project Owner Steps
The owner will see your pull request. If he clicks the "Merge pull request" button, our work is done.
Some Advice
When you want to contribute to an open source project, you will spend much time reading and understanding the source code first than doing the modification/fix. With a project with 100,000 lines of code, you can spend close to a month to understand just 1 subsystem. While reading the code, try to get a feel of its coding standards/convention used in that project. If your code does not follow the coding standards, owner is definitely going to reject your contribution.
Why Would Anyone Want to Contribute?
Assuming you are a very passionate and opinionated person, when you see something is not right with the software, you’ll want to fix it. Of course, you can file an issue on their GitHub. Sometimes, the owners ignore your issue or feature request because they have other priorities or more urgent bugs to fix. To see the bug fixed in your beloved project, sometimes the best way is to roll up your sleeves and implement the change yourself.
