Tips for Launching Your First Open-Source Project
Tips for Launching Your First Open-Source Project
Before you get started on creating your first open-source project, take a look at some helpful tips and tricks from this GitHub dev.
Join the DZone community and get the full member experience.Join For Free
New Report Reveals Open Source Risk Is Still a Mystery to Many. Read more.
The year was 2005. The Linux kernel was already massive andit was in need of a new home. The community of committed developers that had built up around the kernel had outgrown its previous home and needed a new, better way to collaborate and maintain safe, reliable version control. In about ten days, this tight-knit community created the source code management we now know as Git.
Open source wasn't new in 2005. But it was about to take off in a way no one expected. The open-source world exists to bring together communities of developers bound by a shared goal. That goal isto make the world a better place with accessible, reliable sofware.
Your first project may not be the size of Git, but studying successful open-source projects like Git can give us important insights into why some projects succeed while others are unknown.
Tip 1: Know the Recipe
Everything great starts with a basic recipe – and so do great open-source projects. Here is the recipe for success in open source: solve real problems, make it easy to use, and find a community of passionate users.
Solve Real Problems
One of my favorite open-source projects is Probot. Probot is a relatively new project. Its quick rise in popularity can be attributed to the fact that it fulfills a very real need for teams who are interested in automating certain aspects of their work. Probot provides an easy way to perform custom actions inside GitHub issues and pull requests. It is essentially a webhook event handler. Webhooks aren't new – they have been around for years. What makes Probot unique is that it eliminates the need to build custom authentication processes and provides an easy API for interpreting webhooks. If I had a dollar for every time someone scratch-built these same processes over the last ten years...well, that's a topic for another day. The point is that Probot eliminates the pain points developers typically experience when setting up these types of services.
Easy to Use
If your first goal is to solve for pain points, then your second goal needs to be ease of use. As a good rule of thumb, developers will only invest one hour in learning how to use your project – and that number is getting smaller every year. Great open-source projects have a predictable set of tools geared toward new users.
Electron is a great example of an open-source project that focuses on ease of use. The Electron project has robust documentation for getting started as well as a quick-start repository that you can clone and explore as a reference implementation. The community has contributed numerous sample apps that are designed to stretch your imagination even further.
Successful open-source projects first need to be successful software projects. The relationship between an open-source project and its community is one of mutual fulfillment. Passionate users will have a vested interest in adding new capabilities and in making your project more secure and reliable. The users of your software will become contributors to your project. How you treat these users will ultimately determine your success in building a community. In the beginning, you will play the role of product manager, senior developer, and community manager. As the community grows, you will find passionate contributors who share your vision for the project and are eager to support you by taking on some of these roles.
By creating a welcoming environment for your future contributors, coaching them, and accepting their changes, you show them that they are valued. These heavily invested users will share your software with their colleagues. This results in a cycle of value that repeats throughout the life of the project. To put it simply, if your project doesn't have any users, it will have very few, if any, contributors.
Tip 2: Embrace the Role of the Maintainer
When you open-source your project, you put on a new hat: that of a maintainer. Gone are the days when you can spend all your free time gleefully adding new features to your project. Open-source projects are like gardens, they need constant tending and weed control.
Tending the Project
When developers are contemplating whether to use an open-source project, they look for a few key things. These things include a License, a Code of Conduct, and some key indicators of project health:
Is your project being actively maintained and updated? The world of software moves at a startling pace. If the last commit on your project was over six months ago, it may not be receiving critical updates.
Are bugs being handled? Check the issues. If bug reports go unacknowledged or unresolved, this is a red flag to many prospective users and contributors.
As a maintainer, your role is to constantly tend to the project. Responding to issues and pull requests, coaching new contributors, and squashing bugs quickly will take time away from coding, but this a necessary trade-off for good project maintenance.
Open-source communities are largely self-policing. As a maintainer, you set the tone for the community and ensure community guidelines are being followed. If a bad actor takes aim at your community, you will want to have tools in place to correct their behavior. One of your greatest assets in these scenarios is your Code of Conduct. The Code of Conduct signals that you will not accept harmful behavior and explains your process for dealing with it.
Tip 3: Be Mindful of the Migration
Whether your project is currently on GitHub or your local machine, moving to GitHub means moving to a public repository. Before you make the move, consider what you may be unintentionally sharing with the world.
Is the Project in a Reusable State?
You may need to make the project more dynamic before you make the move. For example, have you hardcoded values that others may need or want to customize? Can the project be generalized to other common scenarios without making changes to the code?
What Is in Your History?
If your project has been under version control, consider whether all of the history should be made public. For example, is the email address associated with your commits safe for sharing publicly? Have you ever accidentally committed a private key or token? If you aren't 100% sure whether your commits are safe to share, it may be time to start over with version control.
What About Issues and Pull Requests?
Issues and pull requests created when the project was private contains important historical information, but they may also contain information you never intended to share publicly. It may be wise to move the project to a fresh repository when you make the switch from private to public.
Should You Maintain a Mirror Project?
If you will need to maintain some level of differentiation between the project you use internally and the one you are moving to open source, consider how you will pull updates in the open-source project back into your internal project. This is best handled by pulling the open source project in as a dependency.
Tip 4: Setting up for Success
Before you make your project public, you should also spend time thinking about the contributor's experience when they visit your repository for the first time. The open-source community has adopted a set of documents to help make this experience more consistent between projects. If you haven't done it already, you should add these at the root level of your project.
Without a license, it isn't open source. Every open-source project must have a license. The license you choose is important because it dictates how your project can be used, attribution requirements, and contribution of changes. Changing or adding a license after making your project public can have some serious implications, so make license selection your first step. For a full discussion on licensing, check out choosealicense.com. An interactive guide will help you choose the perfect license and you can even copy and paste an existing license into your project. You should not modify the language in the license, aside from replacing any placeholder text.
Think of the README as a welcoming entryway into your project. It should include information such as:
• What the project does
• How it is commonly used
• How to get started with the project
• Who maintains the project
• How to get started contributing
• The goals of the project
Contributing to a project takes the relationship to a whole new level. Most maintainers opt to provide contribution details in a separate document. This document should be called the CONTRIBUTING guide and is highlighted for users who are opening issues and pull requests in the repository.
Great contributing guides provide the following details:
• The types of contributions you accept
• The preferred process for proposing and contributing changes
• The process of building and testing
• An overview of the system architecture and dependencies
• The location of most commonly updated files
Code of Conduct
Healthy communities conduct themselves in a kind and inclusive manner. To ensure your project's community is healthy, adopt a code of conduct. The code of conduct provides guidelines for the behavior you expect in the project. There are several great drop-in options you can use such as the contributor covenant found at contributor-covenant.org.
Tip 5: Be Prepared to Find and Nurture Your Community
We mentioned earlier that many open-source projects never gain a community simply because they are unknown. Let's discuss specific strategies to prevent your project from becoming one of the unknowns.
Have a Project Landing Page
Don't depend on the GitHub repository as the only face of your project. Your project should have a landing page that helps users who are searching for a solution find the one you have created. Be sure to link back to your GitHub repository in the footer to make it easier for your future contributors to find.
Talk About Your Project
You don't have to love public speaking to promote your project, but it doesn't hurt. If the thought of speaking at conferences sounds terrifying, try writing about it instead. Consider creating a blog where you can tell users about new features and give users the opportunity to share their stories. You can also record videos and create tutorials.
Openly Discuss Friction
Some projects create a repository within the GitHub organization dedicated to discussing friction points in using and contributing to the project. Others prefer issues in the main repository. Regardless of where the discussions take place, your job as a maintainer is to be open and welcoming of these discussions. If you respond with, "You're doing it wrong," or, "We're not going to change that," you risk losing a user and a potential contributor.
Great documentation helps ensure the friction experienced isn't user error – and can become a good way for these users to make their first contribution by clarifying the documentation for others.
Provide Meaningful Connections
Discussions in issues and pull requests are great, but they don't help people form real bonds. Consider adding methods for face-to-face connections. For example, the Probot team holds regular office hours via video conference. Larger projects like Git have in-person gatherings and conferences.
Promote Contributors to Maintainers
Ultimately, this whole business of maintaining an open-source project can be lonely work. Identifying and promoting active contributors allows you to share the work and allows them to contribute in a more meaningful way. You can start by asking them to help you triage issues and pull requests, then consider allowing them to review and approve certain types of pull requests using the CODEOWNERS file. Ultimately, you will find a small number of dedicated individuals you trust to merge pull requests and even help define the strategic direction of the project.
Taking the Next Step
Maintaining an open-source project is challenging but rewarding work. Follow these five tips and you will be well on your way to success.
What will you open source?
Opinions expressed by DZone contributors are their own.