The Git and SourceTree beginner's guide to contributing to open-source projects in GitHub - Part 4 - The Pull Request
This is it! You have forked an open-source project in part 2 and cloned, branched, and worked on it locally in part 3. Finally, you pushed it back to your remote repository in Github and now you want to know if you’re worth your salt. You have to ask the original project owners if they’d be interested in using your code. So you open a pull request.
For the eagle-eyed among you
You might have noticed that, until now, I worked with a branch introducing a target attribute in Concrete5's CKEditor’s link plugin.
That was bogus. Just an example, not real code.
Because I didn’t want to send Concrete5's core team an official pull request for bogus code, I started working on a real feature.
I sent a pull request to add support for the Webp image format in Concrete5 so don’t be surprised is you see a different branch in the following screenshots.
But nice catch! 
Opening a pull request
I went back to my repository in GitHub and was welcomed with this:
GitHub is letting me know a new branch was pushed and offers to open a pull request.
For memory, if I want to merge my branch into any other branch, mine or others’, I have to send a pull request.
So let’s click on that big green “Compare & pull request” button and do just that.
You’ll be taken to a new screen where you’ll have to make choices and give details about your pull request.
Setting up your pull request
The first thing you’ll notice is you’re back to the original Concrete5 repository, not your fork anymore.
You’ll also notice that, at this point, we’re able to merge. Later other tests will run but for now, there seems to be no reason why our code would conflict with the branch we want to merge into.
From the 4 dropdowns presented to you, you’ll have to select (left to right)
- Which repository you want to send your pull request to (could be your own as well)
- Which branch of this repository you want to merge your code into (Concrete5's contributing guidelines state it must be the “develop” branch)
- Which of your repository holds the code you want to merge
- Which branch of that repository specifically
GitHub is pretty smart so you will most likely have all the right options selected by default for our scenario.
Make sure you give your request a meaningful title that is informative at a glance. As of this writing, Concrete5 has 68 pull requests so the core team is not going to spend time reading every detailed explanation before deciding which to use first.
As for the description, the text box is populated with recommendations to follow before submitting your pull request. Read carefully. Once you’re ready make your description informative and detailed. Explain what your modifications do, screenshots are always welcome. Explain any caveats, any possible non-backward-compatible changes…
When ready click the big “Create pull request button” and wait.
Tests are running, please wait
GitHub will run a set of tests to check for code quality, possible conflicts, and other things. It might take a little while depending on what you submitted. You can close the page and come back later or keep staring at it. I often do the latter… 
Important: note that little text “Add more commits by pushing to add-webp-image-support branch on mnakalay/concrete5.”
That means that anything you push to the branch you used for your pull request will be added automatically to the pull request and tests will run again. That is true for as long as your pull request hasn’t been accepted and merged into the core.
Then if everything went well you should see this:
Even more important: You see how it says “This branch has no conflicts with the base branch”? Don’t be fooled, that might only be temporary. Push more to the branch and that might change and you’ll have to deal with the conflicts. Fortunately, it’s not too complicated as we’ll see later.
Other test results you could get are like this:
Dealing with conflicts
Dealing with conflicts is not complicated but it can get tedious depending on how many conflicts there are to deal with.
Don’t let yourself be intimidated by the word “conflict”. What it really means is Git is not sure how to manage the difference between your code and the existing code. It happens sometimes and you just have to tell it how to deal with the uncertainty.
It turns out, after my initial pull request, I pushed some more modifications and ended up with some conflict.
GitHub makes it easy by telling you which files to look at so click on that “Resolve conflicts” button and you’ll be taken to a screen where you can deal with them.
Basically, for each conflict you are presented with 2 choices:
- Either keep what came with your pull request
- Or discard that and keep what is already in the original branch
See how nicely presented it is? Both blocks of code are presented one after the other. Each clearly delimited. In this screenshot mine is the top one (add-webp-image-support) and incidentally am I glad I didn’t name my branch “develop” or I let you imagine the delicate situation it would have created here.
So you just select the one you do NOT want to keep and delete it, right there on that screen.
Important: you also have to delete the delimiters indicated by arrows on my screenshot.
Then go to the next conflict and do the same.
The toolbar at the top gives you useful information and can help you navigate from one conflict to the next.
When you’re done the button “Mark as resolved” will become active and you’ll click it to mark the file dealt with.
After you click it a new button will appear above the toolbar labeled “Commit merge”. Click it, wait a bit and you should be good and done with conflicts.
What’s next
Well, now you wait. Eventually, someone will look at your pull request. They might have questions, comments, suggestions… It can be anybody really but only specific people have the power to merge your code into the original branch.
Answer questions, take suggestions into account, make any modifications requested.
And with a little bit of luck and your immense talent, of course, your pull request will be accepted.
Final words about etiquette
I pointed out several times at the contribution guideline document and made it clear that you should read it and follow its rules.
You may have noticed though that I didn’t necessarily follow all those rules myself.
For instance, it is better to submit pull requests that solve a problem from an existing issue report. There was none concerning support for the webp image format so the proper thing to do in that case would have been to first post an issue report and only then send my pull request referencing the issue report.
To learn more about etiquette and open source projects I strongly suggest you read Sarah Drasner’s very informative article “How to contribute to open source projects” over at css-tricks.com
