New to the world of open source? You’ll likely make a few mistakes in your first open-source project 🤷♂️. In this article, I’ll share key takeaways from our experience building Latitude, covering what you need to know before launching your first open-source project.
If you’re considering taking the plunge, this article is for you!
How to properly set up an OSS project on GitHub
A well-configured project requires more than just a basic setup. It needs detailed information to give potential users and contributors a clear understanding of the project’s objective and functionality. This can be achieved by crafting a clear and concise project description, accompanied by a comprehensive README file that provides step-by-step guidance on how to use the project. This article offers invaluable insights on what to include in your README files and provides tips on writing an effective one.
Beyond that, it’s also essential to establish a contribution guideline and a code of conduct to maintain a respectful and inclusive community.
A contribution guideline provides clear guidelines for making contributions to the project. This includes instructions for submitting issues and pull requests, as well as outlining coding standards and best practices. A code of conduct, on the other hand, sets the tone for a respectful and inclusive community, covering aspects like language choices, behavioral standards, and more.
Check out Latitude for examples of all these.
Choosing the right license
When I started my first open-source project, I underestimated the importance of choosing a license that fitted my project.
Open-source licenses protect users and contributors and govern how others can use, modify, or distribute an OSS project. There are two broad categories of open-source licenses: Copyleft licenses and Permissive licenses.
Copyleft Licenses ensure any derivative work inherits the original OSS license and this can protect the original author from bad actors abusing their work. Latitude, for example, uses an LGPL copyleft license, which grants some protections against commercial competitors using Latitude to compete with us. Permissive licenses, on the other hand, are less restrictive and don’t enforce any license reuse in derivative work.
Likewise, it is very important to have all contributors sign a Contributors License Agreement, which stipulates the terms under which intellectual property has been contributed to your project. This ensures contributors cannot easily sue you for code they might have contributed to your project in the past.
To have all contributors sign the CLA, there’s a handy Gtihub Action that automatically requires new contributors to do so.
Version control and branch protection rules
Open-source collaboration often involves working with contributors whom you don’t necessarily trust. To avoid potential disasters, it’s crucial to set clear boundaries for what contributors can do. Failure to do so could lead to mistakes, such as deleting main branch code, which can be extremely difficult to resolve.
Here’s a set of sane defaults we use at Latitude:
- Require a pull request with approval from code owners to merge code to main branch
- Enforce approval after any code change to pull requests
- Require all CI status checks to pass before merge
- Only give permission to merge pull requests to code owners
- Optionally allow your closest team to bypass some of these restrictions
How to maintain coding standards
In an open-source project, it’s essential to maintain coding standards. When code is written with consistency and clarity, it becomes easier to understand, maintain, and contribute to, ultimately making the project more sustainable.
One effective way to ensure coding standards are upheld is by incorporating linters like ESLint into the development workflow. Linters scrutinize code for syntax errors, formatting inconsistencies, and stylistic issues, providing instant feedback to developers on how to improve their code.
In addition to linters, code formatters like Prettier can further reinforce coding standards. These tools automatically format code according to pre-defined rules, eliminating inconsistencies in indentation, spacing, and syntax.
By combining a linter with a code formatter, open-source projects can establish a unified coding standard that is both easy to enforce and maintain. This not only improves the overall quality of the code but also creates a more welcoming environment for new contributors to join and contribute to the project.
How to manage new releases
Managing releases in an OSS project can be complicated, especially when publishing versioned packages of your software. In contrast to software-as-a-service, where you control the version users access, OSS users can install a particular package version and never update it. This increases the importance of shipping stable and bug-free software.
As a general rule, I recommend against completely automating the release of your software and instead have a manual approval step required at some point in the process. Tools like changesets, the one we use at Latitude, greatly help with this. Changesets takes care of publishing new packages, updating changelogs, and tagging releases, yet it can only do so via automatic pull requests that have the same approval requirements as any other PR at Latitude.
Some more recommendations include maintaining proper human-readable changelogs, tagging releases, and making sure you follow semantic versioning – package managers rely on it for safely keeping project dependencies up to date.
Lastly, a word on prereleases. If you publish versioned packages of your software I greatly encourage you to QA new versions in alpha release. When properly tagged, package managers will ignore these package versions, allowing you to properly and safely test new features in production-like environments. Changesets can also help you with prereleases.
Security best practices
Security practices in OSS projects are not much different from the ones you’d follow in a closed-source project. So here’s a somewhat comprehensive list we follow at Latitude:
Update dependencies regularly: Make use of automated tracking of minor dependency updates with tools like Dependabot, and try to update any major version of your dependencies every so often – at Latitude we review all our dependencies once a month or so.
Code Reviews: Implement a code review process, especially for the sensitive areas of your code that might deal with production secrets.
Access control: Implement role-based access control to restrict access to sensitive parts of your project, control who can trigger new releases, and who can push code to your main branch. GitHub provides tools for all of these.
Secure storage: Never share production secrets in OSS code, ensure only code owners and administrators have access to sensitive areas of your org like shared password managers, PaaS providers and whatnot.
These practices will only strengthen your project’s security; it’s best to keep up with them.
Conclusion
In conclusion, launching a successful open-source project requires careful consideration of several key factors, including defining the project’s purpose and goals, choosing the right license, setting up a proper project on GitHub, understanding version control, maintaining coding standards, managing new releases, and implementing security best practices.
By learning from the mistakes and experiences shared in this article, first-time open-source contributors can avoid common pitfalls and set their projects up for success.
Thanks for making it to the end of this article. I hope you found the article helpful!
Do well to help me
Latitude is an open-source framework for embedding analytics into your application using code.
Please consider giving it a Star on GitHub.
Lastly, if you have any questions about what I've shared in this article, you can drop a comment below.
I hope to have you read my next piece! 😃