GitHub has been experiencing a phenomenal success parallel to the increased adoption of open source software. The latest statistics from GitHub show more than 96 million repositories, over 31 million developers and over 2.1 million organizations.
This represents a massive joint R&D effort worth billions of dollars, and if you ever thought of improving your GitHub presence and attracting more users and developers to your project, here are twelve recommended practices.
The practices will also help you to securing your account, and being more precise about licensing, as well as maintaining good housekeeping.
- Secure your GitHub account with two two-factor authentication (abbreviated 2FA) which adds an extra layer of security to your account. With 2FA, you have to log in with your username and password and provide another form of authentication that only you know or have access to. GitHub provides a great tutorial on this topic.
- Create firstname.lastname@example.org (or similar) and make it visible on your GitHub organization for people who want to contact you with respect to the code you’re making available on GitHub. It would ideally forward the emails to your open source program office and your open source legal counsel as some of the inquiries you will get may be related to licensing or compliance.
- Ensure that every repo includes a LICENSE file. This practice should not come as a surprise from a company that cares about and creates compliance tooling. In fact, this has been one of the areas that GitHub is trying to bring awareness to its users after a survey that demonstrated that a significant number of GitHub repos don’t actually have a license attached to it. These findings motivated GitHub to launch their “Choose a License” initiative to help developers chose a license for their open source software. We would also recommend reading this tutorial on how to add a license to you repo.
- Add a README file to your repos welcoming new community members to the project and explaining why the project is useful and how to get started. As a reference, we would recommend this brief tutorial on creating README files.
- Add a CONTRIBUTING file to your repos explaining to other developers and your users’ community to contribute to the project. At a high level, the file would explain what types of contributions are needed and how the process works. For more information, please refer to “Setting guidelines for repository contributors”.
- Since we’re on a roll here adding more files, we would also suggest adding CODEOWNERS. There’s also a tutorial for this too!
- There has been a noticeable increase of efforts in open source projects to better the diversity of open source community and ensure that newcomers are welcome and feel encouraged to participate in the project. How does that relate to a Github repo? Well, you have now the ability to add a CODE_OF_CONDUCT file that sets the ground rules for the participants’ behavior and helps to facilitate a friendly, welcoming environment. While not every project has a CODE_OF_CONDUCT file, its presence signals that this is a welcoming project to contribute to and defines standards for how to engage with the project’s community. For more information, please refer to “Adding a code of conduct to your project”.
- It is also recommended to add a SUPPORT file to let users and developers know about ways to get help with your project. For more information, see “Adding support resources to your project”.
- Why would anyone keep old and inactive repositories featured in their organization? For that, we’d recommend you archive these repos to flag to your uses and other developers that you’re not maintaining them. How would you do that? Well, there’s a tutorial that provides step-by-step instructions.
- We’re big fans of issue template and pull request templates and we recommend projects to adopt these templates for their projects. Why? Well, these templates help you customize and standardize the information you’d like contributors to include when they open issues and pull requests in your repository. For more information, please refer to “About issue and pull request templates”.
- Achieve and maintain a Core Infrastructure Initiative Best Practices Badge for your project: The Linux Foundation’s Core Infrastructure Initiative (CII) Best Practices Badge is a way for open source projects to show that they follow best practices. Projects can voluntarily self-certify, at no cost, by using a web application to explain how they follow each best practice. The CII Best Practices Badge is inspired by the many badges available to projects on GitHub. Consumers of the badge can quickly assess which projects are following best practices and as a result are more likely to produce higher-quality secure software.
- For large companies, consider a central authority (GitHub Czar) that manages GitHub presence, grants appropriate access, defines and implements best practices, gathers and analyses GitHub stats and provides recommendations to improve engagement with the developer community, etc.