Practical Steps To Contributing To Free And Open Source Projects
step-by-step tutorial on contributing to open source
This is a guide on how to get started contributing to free and open source software (and any other software for that matter that uses git as its version control system). If you are unaware of what free and open source means, you can learn more about it here.
In case this is your first time of hearing the word git, you are in luck. I wrote a detailed tutorial on git, you can learn more about it here.
For this tutorial, we are going to be contributing to a repository on Github (though the things learnt in this tutorial can easily be applied to other code hosting platforms like Gitlab and Bitbucket). The plan is to guide you as you go through the processes involved in contributing to open-source projects.
Without wasting much time, let’s get started:
Step1: Fork the repository
Click on this link to go to the github repository we are going to be contributing to (you need to create a Github account if you don’t already have one). Now that we are on the repository, click on the fork button (highlighted on the image below) to copy the repository from the account of the owner to your Github account.
Step2: Clone the fork
After forking the repository, the next step is to clone the repository to your local machine. Click on the clone button dropdown (highlighted on the image below) to copy the clone url (make sure that the url you copied is that of the fork that lives on your own Github account, this will become important later).
Now create a new folder on your local machine. Open the command line right inside the folder (Shift + Right-Click on windows) and type the following to make sure you have git installed:
If you get an error, it means git is not installed on your local machine. You can follow this link to download and install git on your local machine. If you have git installed, then continue.
The next thing to do is to do the actual cloning. Type the following into the command line and click enter:
git clone <repository url you copied>
to change directory into the folder that contains the git repository you just cloned
Step3: Add upstream
Now go back to this repository on Github and copy the clone url as well (like we did in step 2). In your command line, type the following:
git remote add upstream <copied url>
Why is this necessary?
To effectively contribute to open source, your local repository needs to be able to communicate with the main repository on Github (to pull changes made by others to the main repository into your local machine), and the fork of the main repository (that lives on your own Github account) (to be able to push the changes you made locally to Github).
After the “git remote add” command, we now have two remotes on our local copy of the git repository.
I. origin (pointing to the fork on your Github account. Added automatically by git because you cloned from that fork)
II. upstream (pointing to the main repository on Github from which you forked)
Note that the name upstream is a convention and not a rule. You can name it anything, like “git remote add main_repo_link <url>. You can even rename “origin” if you want.
To view the remotes on your local repository, use the command:
git remote –v
Step4: Branch and make your changes
Ok now that we have done the necessary setup, the real fun path begins. Type the command:
git checkout –b <your name here or any name you would like to give your new branch>
to simultaneously create a new branch and checkout to it at the same time.
will show you how many branches you have locally as well as the branch you are on currently (should be the newly created branch)
Now open the file “first-contributions.md” (you will find it in the root of the git repository) and add your name to it (remember to save). Now go back to your command line and type:
git add .
git commit –m “this is my first contribution”
pat yourself on the back, you have created your first git commit !!!
Step5: push changes to Github
Now before we push to Github, we need to ensure that our local repository is in sync with any new change that has been made on the main project repository. For that we use the command:
git pull upstream master
Note that if your command line complains about a merge conflict here, you probably made changes to files you are not supposed to make. Open the folder named exercises on your local copy of the repository and go to the folder named 1_git_version_control_exercise. Open the README.md file inside this folder and see how to resolve a merge conflict (your should know that even non significant spaces can cause merge conflicts)
If you had no merge conflict or if the merge conflict has been resolved, then we are good to go. Type the command:
git push –u origin <the name you gave your local branch>
to push your changes to Github
Step6: Create a PR
Open up your browser to the fork of the main repository (that lives on your github account). You find that a button titled “compare and pull request” has appeared on the top of the page, go ahead and click on this button (if this button is not present, try reloading your page).
On the page that was redirected to after you clicked on the “compare and pull request” button, go down and type a clear pull request message into the form provided, then click on the “create pull request” button. If you don't know what pull request title to use, you can use "Added my name to first-contributions.md file"
For a review of what we did, let’s look at the key points:
- fork the repository
- clone the fork
- add upstream
- branch and make your changes
- push changes to Github
- create a pr
If you feel you need to get a deeper understanding of git and why it is important, I wrote a detailed article about it here
That is it people! If you need open source organisations to contribute to, check out Wikimedia