A brief guide to being an effective open source contributor.
Welcome! The fact that you're here means you want to start contributing to open source projects, or you want learn how to be a better contributor. We applaud you for that, and hope you get the most out of this guide. But if you read no further than this section, here are the most important things to take away:
In other words: Be considerate of a projects conventions, and kind to its humans, and you will go much further in your career as a developer.
The following sections are planned. Any contributions or shared wisdom would be appreciated!
This guide won't teach you how to use git, or GitHub, or any specific frameworks or tools. There are many other resources available for those things. This guide isn't a replacement for a project's contributing.md
file either. If you find this guide to be useful, we encourage you to link to it from your project's readme and contributing.md
files.
If successful, this guide should achieve the following, depending on your level of experience:
There are many ways to contribute to an open source project, including:
But you aren't limited to these things. Use your imagination! If you like a project, and you see something that can or should be improved, then you have an opportunity (but not an obligation) to contribute.
Regardless of the details, being an effective contributor means that you're adding value to a project.
Here are just a few of the advantages of adding value to a project:
Before you attempt to contribute to a project, take a moment to get familiarized with it. In most cases you can learn all you need to know within a couple of minutes.
The following items are a pre-requisite for contributing to any project. Avoid creating issues or doing pull requests until you've done all of these things:
contributing.md
file and, if one exists, read it in its entirety before creating issues or doing a pull request. Typically this is in the root of the project, but it might be in .github/contributing.md
The most important detail to consider when creating a bug report is whether or not you should create one at all.
Do research first
Did you research existing issues, closed and open, to see if other users have experienced (and potentially already solved) the same issue you're having?
Also make sure you search Google and StackOverflow to see if users outside of the GitHub community have discussed the issue.
Describe the problem, don't jump to conclusions
Another maintainer and I were discussing this topic recently. We wondered how many issues we've handled that were created with the word "bug" in the title, or something along those lines that ended up being user error or were definitely not a bug. This is a guesstimate, but I think it's conservative to say that only 1 out of 10 reports with "bug" in the title has actually ended up being a bug.
Even if you determine that what you're experiencing is absolutely a bug, it's always better to use a title and wording that describes the actual problem you're having, instead of describing it as a bug. Labeling an issue as a bug is better left to the project's maintainers.
However, the exception to the rule is when a project requires labels to be added to issue titles, and the only suitable label is "bug". In these situations, it's better to follow the rules.
When a bug report is warranted, the vast majority of bug reports should include the following four bits of information:
version
description
error messages
code
Rationale
The easier you make it for a maintainter or members of the community to react, the more likely it is for them to react quickly.
Like you, maintainers have to make decisions about where to spend their time. Not only within a given project, but oftentimes across multiple projects. If you're experiencing a bug and you want to make a report, bug reports that are clearly described and organized are much more likely to get addressed by the maintainers or member of the community.
Providing these details up front will make everyone happy. If you don't provide these details, maintainers will have to ask you for them, which can be annoying for experienced maintainers who have had to ask for these crucial details many times.
The details
Always include the following essential details in every bug report:
Let's review the details in more... detail.
Always, always, always provide the version you're using in bug reports. This can't be overstated.
(No matter how long you've been contributing to a project, or how familiar you are with the code and core team, every time a bug is reported, the first thing a core team member wants to know is: "What version were you using when you experienced the bug?". Core team members even ask one another for this detail when debugging. The bug you're experience may have alreay been fixed in a patch.)
Decribe the bug with all of the details necessary for others to understand what's happening, including:
# paste any error messages here
See GitHub's guide to Creating and highlighting code blocks for more details.
// paste your code into a GFM code block like this. Be sure to use the
// appropriate language label after the first code "fence"
See GitHub's guide to Creating and highlighting code blocks for more details.
Before submitting a feature request, try to get familiarized with the project. Find out if the project has certain goals, or guidelines that describe how feature requests should be made.
WIP
It's not unusual for the maintainers of a project to ask you to make changes to your pull request. Here are some common reasons:
Whatever the reason, it's up to you to decide whether or not to make the changes, and it's up to the maintainers to decide whether or not to merge your pull request.
TODO
TODO
Adding value takes time
Depending on your personal goals, keep in mind that it might take longer and require more time committment to add value to a larger project than it would for a small project.
If you want to become a respected and valuable member of a popular project, consider time investment made by the current maintainers and the project's creator. It's reasonable to expect that it will take some time to become familiar with the project's codebase. Review the project's unit tests. Read the docs. Try to understand the project's goals and direction, and try to get to know the current maintainers and community.
Show your support
Sometimes we find a project we like but just don't have time to contribute. That's okay, there are other ways to show support:
Show your appreciation
Maintainers are people too. You can make someone's day, and even inspire and motivate them to keep doing a great job, by letting them know you appreciate their work. If you use a library in one of your own projects, let the author know you care:
TODO:
Resources mentioned in this guide:
Related information:
contributing.md
guidesIf you contribute to this project, thank you! Please add your name to the following list:
Blake Embrey
[your name here!]
Please visit the contributing guide to learn more about contributing to this project.
Jon Schlinkert
Brian Woodward
Released under Creative Commons. Copyright © 2016, Jon Schlinkert.