99 [PR]oblems: A Beginner’s Guide to Open Source
Between interviewing for full-time positions and finishing up my computer science degree, I’ve been hard-pressed to find the time and motivation to tinker. In an effort to reinvigorate the creativity that initially brought me to computer science, I turned to open source. I figured it would be more purposeful than kicking off another personal project or attending hackathons since many products that I use on a daily basis are maintained by the community. What better way to hone my software engineering skills in my spare time and help shape products that matter to me?
Fortunately, I had this open source epiphany right before Hacktoberfest, a month-long event hosted by GitHub and Digital Ocean in order to encourage public contributions to open source projects, had begun. The stars had aligned for me to make my foray into open source, and by October 3rd, my first-ever pull request had been merged!
When I talked to my peers about how hyped I felt about completing the Hacktoberfest challenge (making four pull requests in one month), my accomplishments were received with confusion. As with any novel technical concept, open source can be intimidating. Experienced engineers often throw around terms like “pull request” and “commit” with little to no explanation. This black-boxing of open source can be scary to new coders, thereby discouraging them from participating in one of the best online communities for learning industry-relevant software engineering skills.
Because contributing to open source validated and grew my existing engineering acumen, I wish to augment its accessibility. To do this, I’ve crafted a brief guide to open source for those unfamiliar with it punctuated by reflections from my first contribution.
What is “open source,” anyway?
Open source means any product or service whose codebase is displayed publicly online, and is available for improvement by anyone. Open source is the opposite of closed source, or the case in which a product or service does not have a publicly accessible codebase. Open source projects are built and continuously updated by maintainers— engineers dedicated to managing and building a given project as a job or side hustle — and anyone else who wishes to contribute (like you!). Contributing to open source allows you to give back to products and communities that matter to you.
Do open source contributions required a coding background?
No! Many open source repositories have a documentation file that essentially explains their purpose and how to run the code. These files are typically written in Markdown, which is regular text with supplementary styling (e.g. emboldening, italicization, bullet-ing), and are almost always called README.md. Updating or clarifying the documentation still counts as an open source contribution, and can be a great way for a beginner to understand the workflow behind GitHub and contributing to open source before tackling a challenging, coding-heavy contribution.
In addition, some repositories have no code at all. For instance, in the Ladies Storm Hackathons GitHub organization, there are repositories that house lists of women’s hackathons and online coding tutorials, all written in Markdown. Since GitHub allows easy group revision of files using Git workflow (more on this shortly), people use it for more than code. Once again, editing these repositories does count as a real open source contribution, and can be a safe way to get comfortable with the mechanics of GitHub.
What are the key open source terms that I should know?
Besides the emboldened terms that have already been mentioned, there are a few other helpful ones to know:
- Git: Open source version control system that allows you and your collaborators (if any) to save multiple versions of code simultaneously. Git can be used on the command line.
- GitHub: Popular website for hosting Git repositories. Repositories on GitHub can be accessed online and via command line.
- Repository: Where the history of a given codebase is stored. One repository typically holds one project, which may comprise of many files and folders.
- Issue: Fix or feature enhancement sought by the maintainers and/or users of an open source repository. Contributions to open source centers around resolving these issues. Issues are labeled in order to help coders determine if they have the appropriate skill set and interest to tackle a given issue.
- Fork: To create a copy of someone else’s repository at a given point in time — often an open source repository — and place it under your username and/or store it on your local machine with the intent of making changes to it. You fork an open source repository in order to start working on an issue.
- Commit: Saved version of code at a given point in time. Commits are organized by commit messages, which the programmer writes to keep track of the changes they made to the most recent version of the code.
- Pull Request (PR): Submission of your changes in a forked repository to the original repository, which is the preferred way to add your contributions to open source projects. Note that your contributions do not automatically get added in: it is up to the maintainer(s) to review, approve, and merge them.
- Merge: Incorporating changes made in your forked repository in the original open source repository. Merges are performed by the maintainer(s) after careful review of a pull request.
Where can I contribute?
From a bird’s eye view, the place to make open source contributions is GitHub. More specifically, to find out if a particular GitHub repository that interests you is seeking open source contributions, look under its “Issues” tab. If issues are still “open”, then the maintainer(s) must need someone to work on them!
My first issue was adding parenthesis and quotation matching to Nteract, an interactive notebook for mixing code, writing, and pictures. I chose it simply because I use Jupyter notebooks regularly, and believe that the Nteract desktop interface significantly improves upon the Jupyter user experience.
If you feel unsure about which repositories best suit your skills and interests, poke around the following websites:
- CodeMontage: Sorted by social cause.
- CodeTriage: Sorted by number of issues and programming language.
- issuehub.io: Sorted by issue label.
- Your First PR: Selected for beginner-friendliness.
How do I contribute?
So you’ve found an open issue that you’d like to tackle. Wonderful! Let the maintainer(s) know by commenting on that issue. Wait for one of them to acknowledge your comment before getting started. Once a maintainer approves you as a contributor, then you can dive into the code.
To create your own personal copy of the codebase, you need to fork the open source repository to your account. This can be done without the command line by pressing the “Fork” button. Upon forking the repository, you can create a copy of the newly forked repository on your local machine, and hack away using your favorite text editor.
Make sure to follow the contributing guidelines for the repository you are contributing to by either reading the CONRIBUTING.md file (if it exists), or by asking the maintainer(s) if any guidelines exist. For some repositories, consistency in commit messages and coding styles allows the maintainer(s) to keep track of changes lest anything go wrong.
What are good resources for learning command line Git?
Although forking and searching for repositories can be done on the GitHub website, much of the heavy-duty work of contributing to open source is done offline utilizing the command line. If you are unfamiliar with accessing and updating GitHub repositories from the command line, I suggest checking out some of the following websites:
- Try Git: Learn Git for GitHub in 15 minutes by typing into a mock command line interface.
- Git: The Simple Guide: Read about all the essential Git commands and their meaning on a colorful and fun website.
- Codeacademy’s Learn Git: Receive instruction the Codeacademy way on how to use Git.
- GitHub’s YouTube Channel: Watch video tutorials on Git concepts at the beginner to intermediate level.
What if I get stuck?
Go on GitHub and alert the maintainer(s)! Chances are, they will be willing to point you in the right direction.
How do I add back in my changes?
Press the “New Pull Request” button in your forked repository on the GitHub website. This is the formal way of asking to have your changes reviewed and, if successful, merged into the codebase. GitHub will automatically compare your changes to the original repository, and prompt you to write a brief message explaining your additions to the maintainers.
So I submitted a pull request. What’s next?
Wait for the maintainer(s) and other designated code reviewers to check out your changes and see if they address the original issue as desired. If not, the maintainer will likely ask you to improve upon your contribution. If all goes well, your pull request will be approved. After approval, the maintainer(s) will merge your contributions into the codebase.
Though it can seem like a walled garden, contributing to open source is just another way to code. Even if you missed the chance to participate in Hacktoberfest, I encourage you to give open source a chance! Open source projects need contributors for the other eleven months of the year, too, and it’s your time to shine.
