Demystifying Open Source: Making Your First Contribution
Full disclosure: This tutorial is inspired by a couple of workshops that I attended at the Virtual Grace Hopper Celebration this year. Thursday was Open Source Day at the conference and, though I didn’t get to attend all of the workshops, I attended those aimed at beginners and learned a lot. I learned enough, in fact, that I intend to participate in Hacktoberfest this year. Hopefully after this tutorial you will have the confidence to participate in the future, as well!
I want to give credit where credit is due — this information was presented to me in the following panels:
- Welcome to Open Source, Women! with Katie Levy (Software Engineer, Amazon) and Samantha Monteiro (Software Engineer, Intuit)
- Experience Open Source — Make your First Open Source Contribution with Neha Giri (Software Architect, Intuit)
Both of these excellent workshops gave attendees the necessary skills and tools to dive into open source. Neha’s workshop focused on the process of contributing to a project. She walked her attendees through the process that I’m going to share here. Katie and Samantha walked through the same exercise but supplemented the workshop with more information surrounding maintaining open source projects. Katie is a maintainer of at least one project and had some great insights on how to manage the project and the community.
The big takeaway that I got from these panels was that you do not have to be a senior engineer or coding genius to contribute to open source. This project is an introductory exercise, but even in the real world there are problems that can be solved by all skill levels. As a matter of fact, a lot of projects need documentation updates. This does require you to be able to dig through the code and learn about it before editing the docs, but what a great learning experience! Let me tell you — being able to read and understand someone else’s code is an invaluable skill. You will never start a job and just start writing your own code. There is always a legacy system and if you can walk in and dive in that will be impressive.
Anyway, I hope that this walk-through will demystify the process a bit and make it less intimidating to start seeking out problems to solve at your own skill level.
Let’s dive in!
Step 1: Your Github Account
Note: If you already have a Github account feel free to skip this step.
Github is the best location to start looking for open source projects, so let’s start by setting up an account here.
A Very Basic Intro to Github
Github is a web-based version control application based on the Git version control technology. The most common use of Github is to store repositories, or codebases, and manage them via version control tools. If that does not make a whole lot of sense keep reading — I’ll cover some vocabulary below.
Github repositories typically hold all files relevant to the codebase. Sensitive files are often excluded, but overall any code, documentation, and configuration files will be stored in the repository. For this reason you should typically be able to clone a project and run it, assuming your local environment is configured correctly. That’s usually the catch…but it won’t be a problem for this tutorial! YAY! 🎉 NO ENVIRONMENT CONFIG! 🎉
Ok — once you have set up your account and confirmed your email address you are ready to get started. Let’s start with some lingo:
Issue: Github repositories allow users to open Issues against a project. These are essentially bugs or tasks that need to be dealt with. This is the place to start when looking for work to complete in an open source project.
Fork: Forking a repository on Github creates a copy of the codebase in your personal account. This is good if you are not the owner and want to make changes — for example, expanding an open source project!
Clone: Cloning a Git repository creates a copy of the codebase on your local machine. You can technically make changes to code via Github’s UI, but if you are doing anything extensive you will want to have a local version to load in an IDE.
Branch: Creating a branch is a way to isolate changes that you are making to a repository. The main or master branch is exactly what it sounds like — the current state of the code. By creating a branch any changes you make will not affect the master branch until you merge the changes.
Merge: As I mentioned above, once you have made changes to a branch you then have to merge those changes to the master branch. There are many ways to do this. If you have the permissions, you can merge code directly into the master branch. If you are working in an open source project, you will need to submit a Pull Request to get the maintainer’s permission to merge.
Pull Request (PR): As I mentioned, this is a request to merge changes from a branch into another branch, usually master. At work we use PRs to request code review prior to deployment. In an open source scenario it alerts the owner that you have changes and allows them to review your work before accepting the changes.
Step 2: Install Git On your Machine
This step is pretty straight forward and Git’s documentation is way better than anything I could write.
Get started here: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
Step 3: Check Out the Repository
We will be working with a repository that exists solely for the purpose of practice, so do not stress about making a mistake. This repo is automated when it comes to Pull Requests, so no one is judging your work.
Repository: https://github.com/firstcontributions/first-contributions
Go to the link above and give the repo a good look. If this is your first time in the Github repository feel free to dig around and get a feel for the UI. You should see an Issues tab at the top, files listed below, and if you scroll down you’ll see the README.md file displaying. Typically a repository will include a README file with documentation — it’s convenient because that file is automatically picked up and displayed in the repository’s UI.
Step 4: Fork It!
Once you’re feeling comfortable navigating the UI, check out the very top right corner. You should see a button labeled Fork — like this:
Once you have forked the repository you should be able to navigate to your personal page and see a copy of the repository there. This is what it looks like in my profile:
Step 5: Clone It!
Now that the repository lives in your personal space you should clone it from there. We know that cloning means creating a local repository, but how does one go about actually doing that?
Local vs. Remote Repositories
When using Git to push and pull code you are interacting with two different repositories. They are linked, but they are not the same. Your local repository is created on your personal machine. This happens either when you clone a project or you initialize a Git repo in a new project. When you commit changes to the code that runs on your machine, you are interacting with the local repository.
The remote repository exists on Githubs servers and is the repository that you interact with via the Github UI. When you push changes you are updating the remote repository to match your local repo. The remote repository is also the one that other users will interact with and possibly pull down into their own local repository. The important note here is that there can be many local repos connected to one remote repo.
I recommend using command line tools, which may sound intimidating, but it’s more simple to get started and it’s portable between any IDE or environment. Can you tell I don’t enjoy excessive environment configuration? We installed Git in step 2 and that’s all the required setup there is. 🙌
So, let’s dive right in! Open whichever terminal you have access to. For Windows users hit the Windows key and type “cmd” then hit enter. On Mac just run the Terminal application. Navigate to whichever directory you would like to store the repo folder (it will create it’s own folder with the same name of the repo to hold all the files). If you’re new to using a command line interface to navigate, try these two commands:
mkdir REPOScd REPOS
That will create a directory called “REPOS” and then move you into the directory. Next execute the following clone command:
git clone https://github.com/[YOUR-GITHUB-USERNAME]/first-contributions.gitThe easiest way to get a cloning URL is to navigate to the project and click on the green Code button to the top right of the file list. When you click it will drop down a UI with a URL listed — copy that and replace the one in the command above.
Step 6: Create a Branch
Now that the code has been cloned to your local repository it is available to edit. First, though, we should create a branch so that we are not affecting our master branch directly.
Side Note on the Master Branch
Currently there is an organizational push to rename the “master” branch to “main” in order to foster inclusivity in the industry. Github is in the process of making the change, but it is a legacy term, so it will come up occasionally. I am using the term “master” here because the repository that we are working in still uses the phrase and I want my instructions to be clear. Going forward, this may change and I will update the language to align.
In order to create your own brach you need to navigate inside the folder that contains your repository. Use the following command to get there
cd first-contributionsNext go ahead and run this command to create a branch. This is a combination of two commands: git checkout and git branch (the -b flag represents the new branch command). The last bit is the name of the branch. You can name a branch whatever you would like but you should name it something descriptive. There are branch naming conventions, but for now let’s just go with add-your-name, since that’s what you are doing.
git checkout -b add-[your-name-here]Step 7: Make your Changes
Once you have cloned the project there will be a folder in the directory that you selected called first-contributions. Open this project in whichever IDE you prefer. If you do not have a preferred IDE just open the Contributors.md file in Notepad or your OS’s equivalent.
This file has a list of names, many with an accompanying link to a Github or LinkedIn. You should note that this is a .md, or markdown, file. Markdown files read specific syntax as formatting. You might have noticed that the README.md file is the same type — that’s what allows Github to easily and uniformly read the files to display. Therefore, it allows you to use the following syntax to create a link:
[Mandi Gunningham](https://github.com/mgunningham1014)Once you have added your name and any link you are interested in sharing, go ahead and save the file.
Step 8: Push It!
You have now made your change locally (on your own machine), saved it, and now we need to push that change into the remote repository that is stored on Github. There are a few steps in Git that are necessary to push your code. I’ll explain the following commands as we go.
git add Contributors.mdThis command adds the Contributors.md file to the list of files to be updated. Git keeps track of where changes have been made, but you have to tell it which ones you are ready to commit (i.e. save to the repository).
git commit -m “Added my name to the Contributors.md file”This command commits the changes to any files you added in the previous step and also adds a descriptive message (this option comes from the -m flag). This message will be displayed in the repository with the files that were changed, so make it clear what you changed.
git push --set-upstream origin [YOUR-BRANCH-NAME]You created this branch locally, so it does not exist in the remote repository. This command links your local branch to an upstream (remote) branch and then completes the push. It’s convenient that if you forget to run this the first time you push a branch Git will prompt you in the error message. If I’m being honest, I think Git has had to prompt me to set the upstream branch just about 97% of the time. And if it doesn’t have to I usually let it prompt me anyway so that I don’t have to remember the command 😬
Step 9: Pull Request
Once you have pushed your code successfully head back to your web browser and navigate to your own Github profile and into your forked version of the first-contributors project. At this point you can see your branch available by clicking on the drop down that says master — you’ll see the branch name listed there.
You should also see a banner that looks like this:
Once you click on that you will be presented a Pull Request form to fill out. you may add comments to the request in this step, but it’s not required. You really just have to click the Create Pull Request button at the bottom right.
At this point it will load the PR that you just created. It is now being reviewed (by a bot) and after a moment or so you should be able to reload and see that the change was merged.
Step 10: Check It Out!
As I mentioned a while back, the First Contributions repo has a lot of automation built in. Your Pull Request will be accepted automatically, assuming you didn’t do something crazy, like alter a file other than Contributors.md. Give the bot a minute or so after submitting the PR and go check out the file in the master branch in the maintainer’s repo. Your name should appear in the list as you added it!
Drumroll…
Congrats! You have successfully contributed to an open source project! You are awesome and capable! 🥳 🎉
Now go have fun out there on your next big open source adventure!
Please comment below if you have any questions or suggestions about this tutorial. Of course, I’d also love to hear if this walk-through helped you start your open source journey!
