This is part three of a four-part series on getting started with open source projects. Check back for new parts in the following weeks.
Contributing to open source projects is exciting. It’s an opportunity to show your skills while learning how popular projects, frameworks, and libraries are built. Being a contributor expands your capabilities, introduces you to new communities of passionate open source contributors and helps you think through how to collaborate in the open.
However, contributing isn’t always easy. If you don’t follow the contributor guide or style guide, for example, your pull request (PR) might not get accepted.
In this post, we’ll cover six tips to help you make valuable, focused, and effective contributions to open source projects.
1. Ensure the contribution is needed
When you set out to make your first contribution, start with the project’s issues board. Look for a straightforward issue that you know you have time to dedicate and show your skills. Be careful with issues that have been lying around too long. Often old issues have already been solved, but not marked as closed. If you’re not sure, reach out to the maintainers and ask if the issue still needs to be addressed.
Keeping an open source project healthy goes beyond new features or fixing bugs. Project maintainers are also responsible for reviewing collaborator PRs. Depending on the project, this might mean a lot of submissions. If your submission is declined, don’t get discouraged! If you want to propose new features to a project, create an issue to discuss your proposal before submitting your PR. Once you get a green light from the project members, chances are your submission will result in more collaboration with the maintainers, which eases the process.
Another thing to keep in mind is that members of open source projects will tag issues that are good for beginners. For example, in the Node.js project’s Contribute Page, they tag recommended beginner-friendly issues:
2. Solve one problem at a time
Maintainers love collaboration and quality. Ensure your project is within reach and your contributions not only provide value to the project, but it’s also something you’re confident you can complete.
If you’re working on a larger submission, try breaking up your issues into multiple issues by creating one branch per issue and submit them for review separately. Small changes with a narrow scope increase the chances that your PRs will be reviewed and accepted in a reasonable time.
Additionally, give your PR a simple yet meaningful title; for example:
- Fix ticket #741: Name validation should be case-insensitive
- Add three entries to the FAQ covering internationalization
- Change all occurrences of
Now compare those to the following:
- Fix ticket #741: Name validation should be case-insensitive. Also, clarify the wording of error messages in calls to the logger.
The latter contribution might be rejected because it combines two unrelated tasks: fixing a name validation and correcting error messages.
The intent of your contribution must be clear for everyone on the team. Maintain effective communication by giving your PRs meaningful titles and concise descriptions that explain what you have changed and why.
If the project has a style guide, feel free to use it, and follow how the maintainers recommend submitting your project.
3. Understand project guidelines
Before doing any work, take the time to read the project’s contribution guidelines and style guide. The guidelines describe what the project team expects from new contributors and how they should proceed in each step.
This includes instructions ranging from contributor etiquette to technical details, such as creating branches and pull requests, coding style, committing messages, and testing requirements.
However, if no such guide exists, make sure your code and tests stay in harmony with the project’s overall standards and practices.
4. Aim for full test coverage
Maintainers invariably care about code quality and robustness. Some projects require 100% test coverage for all pull requests, while others have less strict rules. This information is usually stated in the project’s contribution guidelines.
Regardless of the testing requirements, always aim for full test coverage. Run your changes locally against existing tests and create new ones so that your code is entirely covered. Also, ensure your changes don’t disrupt the existing project features. Once you feel comfortable with testing the project, you can even contribute by creating new tests for insufficiently test-covered code submitted by other contributors.
5. Don’t forget the docs
Remember to communicate your changes not only to other team members, but also to the entire community. Update the project documentation, such as the README file, to clearly describe what bug fixes, new features, and other changes you’re including in your PR. If it helps, provide code snippets and screenshots to illustrate your description better.
Contributions often fall behind in updates to the documentation. Maybe a sentence or two is added to the docs or the wiki, but is that enough? Should the FAQ be updated as well? Are there other parts of the docs that would benefit from an update? Docs that say two different things in two different places about the same feature are among the most frustrating things in software.
6. Ask for a review
Before you submit your PR, ask someone to proofread it. This person doesn’t even have to be familiar with the project—they just need a general idea of what you’re doing. Maybe you haven’t explained the PR clearly, or your test cases don’t look extensive enough. An extra pair of eyes may help catch any issues before you ship the PR.
Some projects have a list of reviewers, so you can reach out to one of them and ask for a peer review.
Get ready to succeed
Contributing to open source projects is easier and more enjoyable if you take simple steps and are careful and conscientious. Be considerate of other team members’ time—it’s a habit that project maintainers will appreciate.
Everyone in the open source community—from beginner developers to veteran engineers—benefit from the open source projects. Contributing to them is an excellent way of giving back to the community.
The tips we’ve discussed in this article aren’t the only ways to make great open source contributions—but they are a good start.
Want to contribute to an open source project at New Relic? Check New Relic Open Source and start contributing today.