Since I started focusing on contributions to open-source projects a few years ago, I’ve opened and had merged hundreds of Pull Requests. This article outlines some of the lessons I've learned from contributing to, authoring, and maintaining popular open-source projects.
Creating Open Source Projects
Avoid creating projects that you cannot or will not maintain. Open-source projects require ongoing attention to address issues, update dependencies, and incorporate new features. If you do not have the capacity or commitment to maintain a project, it is better not to release it to the public.
Your code should be easily understood and be maintainable by others. Clear documentation, consistent coding standards, and well-organized codebases are essential when introducing an open source project. This not only facilitates collaboration but also ensures that others can step in to help with maintenance or contribute new features.
Avoid creating packages that are too specific. The more generalized and flexible your project, the broader its appeal and utility to the community. By focusing on creating versatile and widely applicable projects, you can attract a larger base of users and contributors.
Automate everything. To streamline the maintenance and management of your projects, use of GitHub workflows and features like Dependabot whenever you can. Automating processes such as merging Dependabot PRs, running test suites, marking issues as stale, and updating the changelog can significantly reduce the manual workload. These tools ensure that your project remains up-to-date and stable without constant manual intervention.
Contributing to Open Source Projects
Target projects that you use frequently. Familiarity with the functionality and nuances of it puts you in a position to provide meaningful features or fixes. Whether squashing bugs that you’ve discovered or implementing features you have use cases for, your contributions will likely address needs that others have also encountered.
Your contributions are public and are a reflection on you as an engineer. Remember that potential employers may look at your previous work. It's important to think carefully about the quality and thoroughness of your contributions; each pull request you make is a demonstration of your abilities and your understanding of software development. By consistently contributing well-structured, tested, and documented code, you not only support the projects you care about but also build a strong professional reputation that can open doors to future opportunities.
Open thoughtful pull requests. The clarity and thoroughness of your PR descriptions make a significant difference in whether or not it gets merged quickly, slowly, or at all. Start by summarizing what the pull request does in a few sentences, then drill down into the important points below. This approach not only helps maintainers understand the scope and purpose of your changes quickly, but also facilitates a timely, smooth review process.
Keep your pull requests small and focused. Each PR should add a single feature or fix a single bug. This streamlines the review process for maintainers, enabling them to review and merge your code more quickly. Likewise, it’s also easier to address any requested changes promptly. A small, well-defined PR is less likely to introduce unintended side effects and is generally easier to test and validate.
Include unit tests. Responsible maintainers will rarely merge code without appropriate tests, as they help ensure that new changes do not break existing functionality. By including unit tests with your Pull Request, you’re respecting the maintainers' time and reduce the back-and-forth that can occur when tests are missing. Even if your PR seems trivial or is already covered by existing tests, demonstrating that you've thought about testing can expedite the merge process and reflect positively on your contributions.
Update documentation when you make API changes. If the project you’re contributing to has existing documentation, remember that someone took the time to write it; respect this effort on their part and make sure you update it accordingly, including using a similar tone and style. This ensures that other developers can understand and effectively use the new or modified features you have implemented. Neglecting this step can lead to confusion, undermining the usability and reliability of the project.
Respect the time and effort of maintainers and contributors. You’re a user of the project and have benefited from the time and effort of others. Acknowledge the hard work and dedication when you can. Demonstrating appreciation and respect allows you to receive it in return. Always be considerate and courteous.
Respect existing code and writing styles. Remember that this isn’t your project - it’s someone’s, though, and their preferences matter. Whether it’s two spaces for indentation instead of four (or even - gasp - tabs), or the writing style of the documentation, show the original author the respect of using their style preferences.
Maintaining Open Source Projects
It’s a privilege, not a right. Being a maintainer and having the ability to triage issues, review and merge Pull Requests and release new versions is a privilege, not a right. This role comes with significant responsibility and trust, and should be approached seriously. Your actions as a maintainer can directly impact the quality and reliability of a project; they will also affect the experience of the project’s users. Likewise, your actions can impact the reputation of others, such as the original project author. Be mindful of this.
Get input from others. When uncertain about how to address an issue or handle a pull request, don’t hesitate to seek input from other maintainers. Collaboration and communication are key to making well-informed decisions that benefit the project and its community. Leveraging the collective knowledge and experience of others helps ensure that the best possible solutions are used.
Be appreciative. A simple thank you to a contributor or author of a bug report can go a long way. Recognizing the efforts of others not only strengthens open source community but also motivates continued contributions and engagement in the project.
If you're interested, check out some of my open source contributions in my GitHub Organization or my GitHub profile.
Follow-up edit - See this fantastic response article by Tom Herrmann. It's very well written and reasoned out, and it's worth a read. Thanks, Tom!
Top comments (4)
Great blog, thanks for sharing @patinthehat
I followed you on GitHub and you have a nice organization!
Package
coverage-checkseems interesting to me. Definitely will try it :)Thank you! Feel free to ping me on X/twitter if you'd like to chat, contact info is on my GitHub profile.
Hey Patrick,
I wrote a reaction to this post on my blog:
gummibeer.dev/blog/2024/lessons-fr...
Hello @gummibeer
Just wanted to ask you about this? Text is showing only when I hover it