This is the multi-page printable view of this section. Click here to print.
Background on Open Source Contribution
1 - Types of Open Source Contribution
This page was written with reference to GitHub’s Open Source Guide.
In open source projects, software developers mainly contribute by modifying source code to fix bugs or improve features. However, developers are not the only ones who can contribute to open source projects. Open source projects need various types of contributions, such as documentation and design, as described below.
Writing Documentation / Translation
- Write project documentation and tutorials. (e.g., PyPA’s contributors did)
- Write the project’s newsletter or summarize key points from the mailing list.
- Translate the project’s documentation into your own language.
Testing / Creating Issues
- Test whether the software works correctly.
- Test whether it builds / installs as described in the documentation.
- Check whether the documentation and API are written consistently.
Design
- Improve the layout, menus, and so on of the project’s website. (e.g., Drupal suggest)
- Create a style guide so the project can have a consistent design.
- Contribute to creating a new logo or T-shirt. (e.g., hapi.js’s contributors did)
Writing / Reviewing Code
- Find an open issue you can resolve. (e.g., @dianjin did for Leaflet)
- Add new features.
- Improve tools and testing for automation.
- Review code submitted by others.
- Become a mentor to other contributors. (e.g., @ereichert did for @bronzdoc on Rust)
Marketing
- Promote the project’s purpose and usefulness in various ways, such as on social media and through seminar presentations.
Events
- Plan and host various gatherings such as the project’s conferences, workshops, and meetups. (e.g., fzamperin did for NodeSchool)
2 - Open Source Project Membership
How can an open source project continue to develop high-quality software through collaborative work? How can many people who do not know each other write code together and produce stable software? Open source projects achieve this through clearly defined roles.
Leader
Every project has a leader, and the founder usually takes on this role. The leader determines the direction of the project and is responsible for the final decision when a decision is needed. The leader may be an individual, but for large projects, a Steering Committee is organized to perform the leader’s role.
- For example, Linus Torvalds, as the original author of the Linux Kernel, has the final say on every matter of its progress.
- In the case of the Node.js project, the Technical Steering Committee performs the leader’s role.
Maintainer
Maintainers are core contributors who possess the most trusted technical capabilities in the project. They are delegated specific areas by the leader and take on the role of managing them proactively.
Committer
Committers are those who sufficiently understand the code of specific modules in the project and contribute regularly. They have the authority to review and approve contributors’ contributions, and for certain modules they can merge without the maintainer’s approval.
Contributor
Anyone who has contributed, even in a small way, is a contributor. Contributors contribute to open source projects through methods such as simple bug fixes and documentation. Such contributions are reviewed and supplemented by experienced committers and maintainers, and then merged into the repository.
User
Users play the role that determines the success or failure of an open source project. No matter how well prepared a project is, it cannot succeed if no one uses it. By using the project and providing ideas such as bug reports and new feature suggestions, users give the project its reason for existing.
- If a project’s leader and contributors do not carefully listen to users’ requests, it is difficult for the project to grow healthily over the long term.
- A project can only be sustained if it grows in a direction that meets users’ needs.
3 - Key Documents in an Open Source Project
To contribute properly, it is important to understand how each open source project works and to act as the project expects. Most open source projects communicate these requirements through documents such as the README and CONTRIBUTING. Open source projects commonly include several such documents, usually located at the top level of the repository. Before contributing, you should use these documents to familiarize yourself with the project’s culture, code of conduct, and contribution methods.
README
The README is the file you see when you first approach a project. It introduces the project, explains why you should use it, how to use it, and more. It is a must-read document for understanding what the project is.
LICENSE (or COPYING)
The LICENSE is the file containing the open source license, which states that anyone may use the project. Every open source project must have an open source license. Without an open source license, it is not open source. In that case, the source code has been disclosed, but the right to use or distribute it has not been granted. Be aware that including such source code in a product or service carries the risk of copyright infringement.
CONTRIBUTING
If the README is a document for people who use the project, CONTRIBUTING is a document for people who contribute to the project. Because it explains what types of contributions are needed and how to contribute, you should examine this document carefully when you want to contribute to open source. Contributors must follow the contribution methods described in this document.
If the project you want to contribute to has no CONTRIBUTING file, ask the community how to contribute. If you do not receive an appropriate response, you may regard it as a project not worth contributing to and look for another project.
CODE OF CONDUCT
The CODE OF CONDUCT, also called a code of conduct or behavioral guidelines, defines the rules of conduct for participants so that the project stays healthy. For example, it emphasizes that there must be no discrimination based on gender, race, religion, age, and so on, that everyone is warmly welcomed, and that participants must act to ensure safe activity. It also explains how to report someone who breaks those rules.
Other Documents
(For large open source projects) documents such as tutorials and governance policies may also be provided.
4 - How to Become a Good Contributor
This page was written with reference to GitHub’s Open Source Guide.
Before getting into how to submit contributions in earnest, let’s briefly look at how to become a good contributor. Of course, since every project operates differently, there is no single right answer. Each time you join a new project, you need to invest time in learning how it operates. Even so, the following points are commonly helpful in becoming a good contributor.
1. Join the Community
Open source projects have a community of users and developers. Each community participates in slightly different ways. Read the documentation the community provides, and join its main communication channels such as the mailing list, forums, IRC, Slack, and bug tracker.
2. Observe for a While
After joining the community, take some time to get familiar with its culture before contributing. Reviewing past communications is a good approach. The more you go through this process, the more likely your first contribution is to be accepted.
3. Understand the Governance
Before contributing, use the project’s management and governance documents to understand how the project is governed. You can learn who makes decisions and how.
4. Start Small
Start with a simple bug fix or documentation change. It is good to learn the process and correct mistakes by making small, low-stakes contributions. Building on this experience, you can contribute more substantially and gradually have an impact on the project.
5. Attend Events
Building lasting relationships with other participants in the open source community is important. The best way to do this is to attend events such as conferences. Nothing builds relationships like meeting in person.
6. Contribute from the Early Stages of the Code
Some people finish developing until the amount of code becomes quite large and then try to contribute it all at once. Such contributions are not easily accepted by open source projects. It is difficult for a project to review a large amount of code at once, and the contributed code may differ from the direction the project wants. Discuss with the community starting from the idea stage, and contribute early in development and often.
5 - How to Identify a Good Project to Contribute To
This page was written with reference to GitHub’s Open Source Guide.
Naturally, you should contribute to open source projects that are related to your work or in an area of technical interest. If there are several such projects, it is also worth considering which one is worth contributing to. Otherwise, your hard-earned contribution may be buried without any response.
The following is a checklist for determining whether an open source project you are interested in is suitable for contribution activity.
1. Is There an Open Source License File?
- Is there a LICENSE file? Typically, there is a file named LICENSE in the root directory of the repository.
A project to which no open source license applies is not open source. Only when the software’s copyright holder grants, through an open source license, the right for anyone to use and distribute it can a company use that software freely. Using software without an open source license at will can create legal risks such as copyright infringement.
2. Is the Project Actively Receiving Contributions?
- When was the most recent commit?
- How many contributors are there?
- How frequent are the commits?
If there are few contributors or there have been no commits for several years, the project can be considered unmaintained.
On GitHub, you can check the commit status under “Commits” at the top of the screen.
3. Check the Project’s Issues
- How many issues are open?
- When an issue is opened, do maintainers respond quickly?
- Is there active discussion on the issues?
- Are the issues recent?
- Are issues being closed?
If issues are not being opened, or if they are opened but not responded to, the project can be considered unmaintained.
On GitHub, you can check the status of closed issues by looking at the “closed” tab on the Issues page.
4. Check the Project’s Pull Requests
- How many Pull Requests are open?
- When a Pull Request is opened, do maintainers respond quickly?
- Is there active discussion on the Pull Requests?
- Are the Pull Requests recent?
- How recently have Pull Requests been merged?
On GitHub, you can see closed Pull Requests by clicking the “closed” tab on the Pull Request page.
5. Does the Project Have a Welcoming Atmosphere for Contributions?
- Do maintainers give helpful answers to questions about issues?
- Are people friendly in issues, forums, and chat (such as Slack)?
- When you submit a Pull Request, does a review take place?
- Do maintainers show appreciation for people’s contributions?
A project that does not have a welcoming atmosphere for contributions is unlikely to develop well over the long term. This can also be a criterion for judging whether a project is worth contributing to.
6 - How to Communicate
This page draws on content from GitHub’s Open Source Guide.
Every part of the open source contribution process is a continuous series of communications with community members. First, keep the following points in mind for effective communication.
Communicate Your Intent Precisely
If you are reporting an error, explain precisely what task it occurred during and how to reproduce it. If you are proposing a new idea, explain why you think it would be useful to the project.
| Good Example | Bad Example |
|---|---|
| “X does not work when I try to do Y.” | “X doesn’t work. Please fix it.” |
Do Not Just Ask; First Try What You Can Do Yourself
Before asking for help, look for the answer in the project’s documentation such as the README, in issues, in the mailing list, or through a search. It is good to show this kind of effort.
| Good Example | Bad Example |
|---|---|
| “I’m not sure how to implement X.I checked the README and the mailing list history but couldn’t find anything about it.” | “How do I do X?” |
Keep Conversations as Concise as Possible
Every contribution you submit has to be reviewed by someone. Some projects accumulate so many contributions and requests that they are difficult to review. Therefore, the more concise your request, the more likely it is to be accepted.
| Good Example | Bad Example |
|---|---|
| “I’d like to help with writing the API tutorial.” | “The other day I was driving on the highway and stopped at a gas station.That’s when an amazing idea about what we should do came to me. Before I explain the idea, there’s one thing I want to show you.” |
Make All Communication Public
Contacting maintainers privately is not a good practice. Keep all conversations public. This allows more people to learn and benefit.
| Good Example | Bad Example |
|---|---|
| (As a comment) “@maintainer Hello, how should I proceed with this PR?” | “(By email) Hello, when will you review my PR?” |
Once You’ve Asked, Be Patient
Even maintainers cannot handle everything perfectly. They also need time to review.
| Good Example | Bad Example |
|---|---|
| “Thank you for reviewing this error.I followed your suggestion, but this time these errors appeared.” | “Why can’t you solve my problem?Aren’t you the maintainer?” |
Respect the Community’s Decisions
Your ideas may differ from the project’s priorities or vision. The community may decide not to adopt your idea. You must accept this. If you cannot find a compromise, or can never agree, you should consider forking and starting your own new project.
| Good Example | Bad Example |
|---|---|
| “I’m sorry the use case I submitted wasn’t adopted, but thank you for explaining the reasons in detail.I understand.” | “Why won’t you support my use case? This is unacceptable.” |
Above All, Maintain Your Dignity
In open source projects, you collaborate with members from all over the world. Depending on language, culture, region, and time zone, there are differences in communication styles. Also, because you communicate through writing rather than face to face, it can be difficult to convey tone and mood accurately. A good way to overcome these difficulties is to always interpret others’ writing in good faith. When declining someone’s proposal, be polite, and express your own position clearly. Conduct yourself with dignity in the online space that is open source.