How to create GitHub Pull Request?

The success of an open-source project highly depends on the contributions of the community. As a maintainer of a few open-source projects, I have seen the power of such contributions. On the other hand, there are people who like to contribute but couldn’t because of technical barriers. This tutorial walks you through how to create GitHub Pull Request in a beginner friendly way.

Safe Eyes is one of my open-source projects available for Linux users to prevent asthenopia (eye strain) due to RSI. This tutorial shows you how to contribute to updating the French translation of this application by sending a pull request as an example. However, the process is the same for any pull requests you want to submit to any GitHub repository.

Requirements

• GitHub account
• Git (Install Git)
• Atom text editor (You can use any text editors but I prefer Atom due to its support for GitHub)

Fork A GitHub Repository

Step 1:
Login to your GitHub account and then visit the GitHub repository of your interested open source application. In this tutorial, I use https://github.com/slgobinath/SafeEyes.

Step 2:
Click on the Fork button on the top right corner. It will create your own copy of the above application in your GitHub account.

Clone The GitHub Repository

Step 1:
Click on the Clone or download button and copy the URL.

Step 2:
Open the terminal anywhere you like, and enter the following command. Replace the URL with the URL you have copied in step 3.

git clone https://github.com/lgobinath/SafeEyes.git

The clone command clones the repository into your local computer so that you can make changes.

Sychronize the Code with Upstream Remote

Step 1:
Change the terminal directory to the application folder.

cd SafeEyes/

Step 2:
It is a best practice to add the original repository to your local clone so that you can easily keep your local copy up to date with the official repository. Enter the following command to add the original repository as the remote upstream.

git remote add upstream https://github.com/slgobinath/SafeEyes.git

Step 3:
Ensure that you are in the master branch using the following command.

git branch

Step 4:
To pull the latest changes made in the upstream branch to your local repository, enter the following command. If you have forked and cloned the repository just now, this is not necessary.

git pull upstream master

Create A Feature Branch

Step 1:
You can start changing the code from the master branch. But it is better to make your changes on a separate branch so that it will be easy to merge the upstream changes into your local branch later. Also, you can delete a feature/fix branch at any time.

git checkout -b feature-french-translation

Note: Some projects use different development branch. In such case use git checkout to change the branch to the development branch and then create a new feature branch from there.

The above command creates a new branch named feature-french-translation from the master branch.

Step 2:
Open the project in your favorite editor and make the changes. If you have a hard time choosing your favorite editor, take a look at the Visual Studio Code.

Commit The Changes

Step 1:
After saving and testing your changes, check the status using the following command to ensure the modified files.

git status

Step 2:
Add the changes to prepare the content staged for the next commit.

git add safeeyes/config/lang/fr.json

You can also use the following command to add all the changes.

git add *

Step 3:
Commit the changes with a suitable commit message.

git commit -m "Update the French translation"

Create A Pull Request

Step 1:
Push your new branch to your remote account.

git push origin feature-french-translation

Step 2:
Visit your GitHub repository and select the branch from the drop down list.

You can also click on the Compare & pull request button if it is there, but I follow the normal way of creating a pull request (PR) here.

Step 3:
Click on the New pull request button.

Step 4:
Make sure that the base fork is referring to the original repository and the base branch is whatever the development branch from which you have created your new branch in Step 9. Also, make sure that your new feature branch is selected in the compare drop-down list.

Step 5:
You can scroll down and verify the changes. If you are satisfied with what you have, click on the Create pull request button.

Step 6:
If you go to the Pull requests of the original repository, you will see your pull request there. That’s all you have to do. The repository maintainer will either merge your pull request if everything is okay or ask for modifications.

For the repository maintainer, your pull request will look like in the following screenshot and they can decide on whether to merge your pull request or not.

If your pull request is merged, your changes will be available in the parent repository. If this is your first pull request, your GitHub username will be listed in the “contributors” list.

Updating and Cleaning Your Repository

Once your PR is merged, you don’t need your feature branch anymore. You can delete by following these steps.

Step 1:
Switch to the master branch and pull the changes including your commits.

git checkout master
git pull upstream master

Step 2:
Push the changes to your forked repository.

git push origin master

Step 3:
Delete the local branch using the following command.

git branch -d feature-french-translation

If you are confident that your changes are merged, you can use -D instead of -d.

Step 4:
Delete the branch in origin using the following command.

git push origin :feature-french-translation

To learn Git, read the Atlassian Git Tutorial. Show your support by adding new features and fixing bugs in open source projects that you are using. If you have any questions, please comment them below.