Contributing to the open source community is one of the best ways to learn from amazing developers, get into good coding habits and work on great projects. Getting started can be difficult though: Open Source is not just about code being in the open though - set conventions and well-established "rules of engagement" guide the development of most projects. I gave an short talk and this post summarizes the 101 of "Contributing to Open Source".
If you've been around the Open Source block before, be warned that this post does not contain any new ideas, it's just a collection of the best practices observed out there.
The Organization of Development
All good open source projects have strong leadership and a clear hierarchy. People involved with a project usually fall in one of four groups: The Owner is the user or organization that created the project has the project on their account. Maintainers and Collaborators are the users primarily doing the work on a project and driving the direction. Oftentimes the owner and the maintainer are the same. Contributors is everyone who has had a pull request merged into a project. Community Members are the users who often use and care deeply about the project and are active in discussions for features and pull requests.
Most projects have owners and maintainers who guide the development by breaking a complex road map down into small workable items, accepting proposed code changes into the code base and laying out detailed rules about the organization of the project. The convention is to lay out those rules in a Contributing.md file in the root of the project's Git repository.
There are two ways to contribute: Fixing a bug or developing a feature. If the bug is already known or the feature already on the road map, it'll be documented with requirements. On GitHub, those work items are collected and discussed as issues. If you're just getting started with a project, it's a good idea to work on something that has already been put on the "to be developed" list. Don't just work on a feature you'd like to see without discussing it with the project maintainers, it's a good way to work on something that will just get shot down and never touch the main code base. If you found a bug, creating an issue and commenting that you're also willing to fix it is usually greeted with open arms.
Managing Code Bases with Git and GitHub Flow
Even if you used Git before, it's pretty likely that you don't know all of Gits features. Before you dig any deeper, make sure that you're comfortable forking and cloning a repository, staging and committing changes, and creating and merging branches. You'll also need to have no trouble fetching, pulling and pushing changes from multiple remotes. Using a visual interface like the GitHub Apps, SourceTree or Visual Studio is okay, but you should be comfortable doing all these things from the command line - especially if you want to leverage the full power of Git, including stashing, rebasing and cherry-picking. If those things are new to you, check out some of the amazing Git tutorials - both GitHub and Atlassian provide excellent tutorials.
Git is just a tool, so there are multiple ways to organize the work around it. A few popular workflows have established themselves, with 'git-flow' being the most popular one in managed projects centered around the concept of "releases". The trouble with Open Source is that it's released all the time. GitHub releases and deploys to production daily - sometimes multiple times a day. They developed and documented their own workflow, which has in the meantime been adopted as "GitHub Flow" by the majority of open source projects. One of it's qualities is that it's very simple, so it's easy to pick up.
GitHub Flow
- Anything in the master branch is deployable. It might not be part of a versioned release, but it is clean, reviewed and accepted code.
- To get started, you fork the repository into your own account. Right after you forked, the repository will be identical. Any work you want to code is done in a new and descriptively named branch off of
master(for instancefeature-signup). - Commit to that branch locally and regularly push your work to the same named branch on the server. In the case of GitHub, you simply
push. - When you need feedback or help, or you think the branch is ready for merging, you open a pull request using the GitHub website. At this point, everybody gets to see and discuss your code.
- It's pretty likely that you'll want to address concerns or ideas by other coders, so you push code changes to the same branch, which will automatically update the pull request.
- Once a contributer has reviewed and signed off on the code, it is merged into the
masterbranch.
If you'd like to know more about GitHub Flow and the reasoning behind it, check out Scott Gathons post on issues with git-flow.
Making a Good Pull Request
The pull request is the essence of open source development. It's where your code actually becomes a contribution, so it's important to get it right.
Tests
Good software is tested, so many projects contain extensive test suites. Before even making a Pull Request, make sure that your code passes all tests. If you developed something that is not properly tested, write new tests.
Code Style
Contribute in the style of the project to the best of your abilities. This may mean using indents, semi colons or comments differently than you would in your own repository, but makes it easier for the maintainer to merge, others to understand and maintain in the future. Many projects provide tools to check this (like JSCS), but make sure to also observe untested conventions.
Squash Unnecessary Commits
In many cases with small (less tha 500 lines of code) changes, you should consider squashing down to a single commit. This keeps the list of commits in master clean.
Screenshots
If you made any changes to the User Interface or the User Experience, consider adding a screenshot or even a small GIF Screencast to your PR. This allows other contributors to give input on your changes without running the new code.
Descriptive Info
It's a good idea to have a clear audit trail. In the case of GitHub, every commit, issue, and pull request is assigned an ID, allowing you to provide additional information and automate the workflow. If your pull request begins with Closes #34, issue #34 will be automatically closed once your PR is merged. As an added bonus, GitHub will also offer a link to the issue, making it easier for others to understand what you just did. You can mention other people with an @, resulting in a notification for those users. If you mention @felixrieseberg in your code, GitHub will send me a mail to let me know that my attention might be required.
Take Feedback Well
Be explicit about what feedback you want. Usually, another set of eyes on the code or a discussion on the technical approach won't hurt. If feedback is offered to you, understand that somebody took time to read through your code and offer suggestions, so try to not take it personal - even if you disagree.
Don't Stay Strangers
If there's a growing discussion or debate, be open to the idea of a different kind of communication. In fact, once you hit a road block, a small face to face chat might be the best idea.
Many smart people have written equally smart posts on the topic of a good pull request - if you want to think about this more, consider Jason Brenhan's orGitHub's thoughts.
Contributing Without Code
Open Source and software development isn't just about code. There are more ways to contribute - projects are always looking for people that report bugs as an issue, translators, documentation writers, testers or designers.
There's a bunch of projects out there - you should just try to contribute to one of them. If you just want to browse around, check out GitHub's Explore feature, which let's you browse projects. Just pick an issue and code away!