OPEN SOURCE HACKS: ONE QUESTION INTERVIEWS WITH OPEN SOURCE EXPERTS - GitHub Essentials
Open Source Hacks: One question interviews with Open Source Experts - GitHub Essentials
This blog series aims to share simple philosophies, insights, tips, and tricks that can have a positive impact on you and your projects. Each blog features a guest expert providing their thoughts on one open source question. Today’s expert, Intel’s Jessica Marz, answers this question:
“What makes a good GitHub repo?”
Good documentation is key to project success. Get your project off to a strong start by including these elements in your repo:
Project description. Don’t be one of those projects with “No description, website, or topics provided” at the top of the page! Conversely, don’t write a novel. A one or two sentence summary is great—you can give more detail in your README or wiki.
In addition, project repos should at minimum contain the following documentation:
- README file
- LICENSE file
- CONTRIBUTING file
- Instructions for security/vulnerability reporting
README file. This is the ‘front page’ of your GitHub project repository. Make it useful by showcasing important information. Projects should include the following sections in the README.md file:
- License: Identify the license by its OSI-known name, then link to your LICENSE file which contains the full license text.
- Contributing: Link your CONTRIBUTING file to let would-be contributors know how they can participate.
- Instructions for security/vulnerability reporting: Document the vulnerability reporting process in the README.md file itself, explain the process in your CONTRIBUTING file, or create a separate HACKING file to provide the information. Vulnerabilities should be reported separately from regular bug reports, since it is not smart to share publicly how to exploit a security defect.
- Anything else the project team feels is necessary: Installation instructions and how to actually use the project are often good additions.
LICENSE file. This should contain the complete text of the project license.
CONTRIBUTING file. Someone is looking at this to learn how your project accepts contributions, so tell them what you’d like them to do and how to do it! Do you want a bug to be reported as a GitHub issue? It may be helpful to make an ISSUE TEMPLATE available for submissions. Do you want contributors to submit pull requests (again, a template could be useful), or should they submit patches to a project mailing list? Are there particular coding conventions or patch formats that need to be followed? Do you want contributors use the same “Signed-off-by” convention as used by the Linux kernel project for their submissions? Spell it out and don’t be shy about including examples of what you’re looking for!
Instructions for security/vulnerability reporting. As mentioned above, you have some choices about where to place the reporting instructions, but I highly encourage ALL open source projects to have clearly posted instructions for how to responsibly disclose a vulnerability.
Examples of GitHub repositories. The repositories below do a good job, but would be even better if they had a process for reporting vulnerabilities
About the Author
Jessica Marz works in the Open Source Technology Center at Intel Corporation and has been involved in software legal compliance since becoming licensed to practice law. In her current role, she is responsible for defining and managing Intel’s corporate open source software policies and practices. She explains legal stuff to software developers and software development stuff to lawyers.
Other blogs in the series