Whether for a small personal project or as part of a bigger organization, there’s more to open-sourcing a GitHub repository than just making the visibility public.
As part of my day job, I recently had the task of open-sourcing a GitHub repo for a project I have been working on. As part of the process, I decided to compile a list of all the things you should ideally do before, or as soon as possible after actually making the repo public.
This list may seem overwhelming at first, but consider it a guide for things to consider over time to gradually improve the quality of your open-source project!
Choosing a License
One of the most crucial steps will be to choose and apply a license for your repo so that the IP that you are producing is not used in undesirable ways. There are a lot of choices out there, and if you don’t already have some idea what you want, it can be a bit overwhelming to pick. Thankfully GitHub has created a great tool at https://choosealicense.com to help guide you through the selection.
Once you have a made a decision, this guide will help you through the process of actually populating it into your repository.
Documentation
Attracting users and contributors to your open-source project is crucial for its success, and the better your documentation is, the more likely others will join.
Of course details of documentation will vary from project to project, but there are several standard best practices you should consider adding:
Readme
The README.md file at the root of a project is the classic entry point for documentation. This markdown file is what is rendered on the main page when viewing the repo in GitHub.
If you’re looking for some inspiration of what a great Readme looks like, take a look at this curated list of examples and tools.
Security
There are several things you should do to make your project as secure as possible for both users and contributors.
Branch Protection
Most repos will have a main branch that contains the most recent version of source code. This is where changes are integrated into, typically via the GitHub flow. Configuring branch protection rules will help ensure that updates to your code by yourself or other contributors maintain a high quality by requiring that they have received a code review, and any status checks like unit-tests are passing.
For more information on configuring branch protection, see the GitHub documentation on the subject.
GitHub Actions
Workflows provide an open-ended list of useful automations you can add to your project. They are often used for things like running tests or style enforcement on all PR’s to the project. Unfortunately, they can also open potential security risks if not properly configured.
I highly recommend reading this blog series from GitHub on how to keep your workflows secure. It will give you a basic idea of the risks involved as well as how to properly mitigate them.
For even more detail, GitHub's documentation provides a comprehensive list of considerations.
Dependencies
Taking advantage of other open-source projects is a great way to multiply your efforts, but upstream dependencies are one of the biggest causes of security issues. GitHub’s Dependabot tool can be configured to help keep your dependencies up to date which is the best defense against upstream security vulnerabilities. It can even provide alerts to you when security issues are discovered in your projects’ dependencies. It is free to use for open-source projects and I highly recommend enabling it.
Security Policy
It is impossible to always write perfect code, and it is of course possible that your project introduces security vulnerabilities itself. One way to mitigate this potential is to provide a security disclosure policy so that if a community member finds an issue, they can responsibly disclose it.
These docs explain how to attach such a policy to your repo. You can even configure your repo to allow responsible reporting directly within GitHub.
Extra Credit
There is a laundry list of extra things that are nice to have on your open-source repo. They may not be necessary starting with your first commit, but you will often find them on more mature projects.
Contribution guidelines help inform your community how they may best add to your project.
Issue templates can help users format reports of problems they encounter in the way that is most productive towards being solved.
Code of conducts can help ensure a safe, welcoming community for your project.
Anything missing? Leave a comment with other things you consider important for a great, secure open-source project.