Open source software is taking the world by storm and by now, most of us use at least one open source tool every day. Joining the open source community for the first time can seem daunting. Even if you’re not a developer, you can still help the community of software that powers our lives every day.
This post is a text version of my talk given at WordCamp LAX 2017. The slides can be found on SlideShare and a video version is coming soon on WordPress.tv.
For a long time, companies dominated software with proprietary offerings. This meant only a handful of developers could contribute and test before they released that software. This created problems because those developers could not replicate the environment of every one of their users or every use case. This meant more bugs in their software.
To contrast that, a popular open source project may have thousands of people contributing and testing. Thus a saying was born that, “given enough eyeballs, all bugs are shallow”. Firefox and WordPress are a couple examples of tools many of us use that are open source.
How do I add my voice to an open source project?
Before most bugs or new features become code, they are usually filed as an “issue” on the project. Filing an issue on a GitHub project is a good way to get the discussion going.
If you’re looking to contribute, search through the issues for the project you’re contributing to and see if there is any work already in progress.
If there is, great! Add your voice to the conversation and help keep the progress going. If not, now’s a good time to file an issue and start a dialog. As a note, it’s possible to contribute without going through this process. It’s also possible that after you spend hours working on your contribution, the project maintainers will decide that it’s not a good fit (see image below). Creating dialog around an issue before you start can help with this.
This is disheartenening and a waste of both your time and the maintainers. File an issue first and work with the maintainers to decide on a direction. Check for a CONTRIBUTING.md file that details exactly how you’re expected to contribute. When that’s taken care of, you can start your contribution.
Now, we’re ready to make a pull request and get our contribution merged in, right? Well, if you’ve never used git before to keep track of your code, let’s take a timeout for a brief primer on git.
Git is a way to control versions your code, saving checkpoints (called commits) one on top of each other in a tree-like formation. You can move between commits at any time and see the state of the project at the exact time that you made the commit. This makes git useful if you have to undo work or figure out exactly where a particular bug occurred. Each of these commits has a unique identifier, producing a structure like we see below.
To add our contribution to this project, we need to create a “fork”. A for is an exact copy of the project, but in our own GitHub account, so we can actually contribute code to it.
Now, since we’re working on a small addition, we want to create a branch. This is where the tree-based model starts to show. A branch is a separate chain of commits that won’t conflict with other contributors. This system is what makes git great for larger teams of developers. Git ensures that none of their work gets overwritten.
When we’ve got our contribution finished up on our branch, it’s time to get merging. On GitHub, we can make what’s known as a pull request. A pull request informs the owner of the original project that we’ve got a contribution we’d like to add.
The maintainer can review this, add comments, and approve or reject it. If it’s approved, it goes straight into the main project and you can see your contribution to open source! Otherwise, it might take a bit to get there.
For example, some projects run a suite of automated tests against anything that contributed<. For one pull request I made, it failed some of the automated tests, even though it shouldn’t have. I talked to the maintainers and got the issue resolved, but it was an unexpected roadblock. Because open source is public, you can see the whole discussion on GitHub.
Open source maintainers are very busy, especially on bigger projects. Even once you’ve gotten any issues with your contribution resolved, it might take some time to get it merged. Be patient. Make sure there’s nothing else the maintainers need from you as a contributor. If you’ve followed the process outlined here, your contribution has a much better chance of getting merged.
So if you’re going to contribute like we outlined above, you need to head over to GitHub and sign up for an account. If you’ve never worked with git before, you will want to use a program like Sourcetree to make the process easier.
After you’ve got these two things, you’re ready to go. To practice, I’ve set up a repository that you can contribute to without having to write any code. You can read through CONTRIBUTING.md for a review of the process that we’ve outlined above.
– Fork the repository into your own GitHub account
– Create a branch for your contribution
– Edit the main guestbook file and add your name, city and date.
– Commit the changes to save your work.
– Create a pull request against my main repository and I’ll merge your contribution.
If you have any questions or get stuck along the way, don’t hesitate to reach out over email or Twitter