GitHub Pull Request - A Complete Guide For Beginners

The power of open source applications highly depends on the contributions from the community. As a maintainer of two small open source applications, I have seen the power of such contributions. However, there are people who like to contribute but fail because of the technical barriers. This tutorial shows you a top to bottom step by step guidance on how to add a new feature to an open source application that is available on GitHub.

Safe Eyes is one of my open source application available for Linux users to prevent asthenopia (eye strain) due to RSI. This tutorial shows you how to contribute in updating the French translation of this application by sending a pull request.

Prerequisite:

  • GitHub account
  • Git (Install Git)
  • Atom text editor (You can use any text editors but I prefer Atom due to its support for GitHub)
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.


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


Step 4: 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.

Step 5: Change the terminal directory to the application folder.
cd SafeEyes/

Step 6: 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 7: Ensure that you are in the master branch using the following command.
git branch

Step 8: 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

Step 9: You can start changing the code. 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 10: Open the project in Atom or any other editor, and make the changes you want to have.


Did you wonder why I preferred Atom? Note the color highlighting the modified files and lines in the screenshot.

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

Step 12: 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 13: Commit the changes with a suitable commit message.
git commit -m "Update the French translation"

Step 14: Push your new branch to your remote account.
git push origin feature-french-translation

Step 15: 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 16: Click on the New pull request button.


Step 17: 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 18: You can scroll down and verify the changes. If you are satisfied with what you have, click on the Create pull request button.

Step 19: 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.
Previous
Next Post »

Contact Form

Name

Email *

Message *