Note: This template is provided to give you a good idea about the kind of information you should include in a README.md file as a best practice. You know your project inside-out. Write your readme file for someone who doesn't know anything about it. What do you want people to know about your project who are just coming across it for the first time? OASIS Staff are happy to collaborate with you as well.
Further README inspiration can be found here and here.
You may copy and edit this template as you see fit for your project and your community. You are also welcome to use emojis, graphics or images in your README. This file should be reviewed regularly and kept up-to-date.
- Project Logo (optional)
- Project Title
- Badges (optional)
- Description
- Repository Organization (optional)
- Contributing
- Authors and Maintainers
- Support
- Join us on Slack(optional)
- License
- Acknowledgments(optional)
If available, add project logo.
One Paragraph of project description goes here. Include the copy: " is an OASIS Open Project"
Using badges is optional, but they are a nice way to show some key facts and stats about your project at a glance. There are badges for all kinds of things relating to your repository, e.g. to show the license you're using, the programming language, the number of forks, or a CI badge to show build/test status. Be mindful not to use too many badges. You can use Shields to add some to your README. Many services also have instructions for adding a badge. Check out the README of the Open Cybersecurity Alliance project Kestrel to see badges in action.
- State what problem(s) your project solves.
- Note its development status.
- List the most useful/innovative/noteworthy features.
- Note and briefly describe any key concepts (technical, philosophical, or both) important to the user’s understanding.
- Link to any supplementary blog posts or project main pages.
- Compare/contrast your project with other, similar projects so the user knows how it is different from those projects.
- Highlight the technical concepts that your project demonstrates or supports. Keep it very brief.
- If available, include screenshots and demo videos.
You can use this section to give a brief overview of what can be found in this repository, e.g. documentation, meeting minutes, or templates. A good example of this can be found in the README of the OASIS OpenC2 TC repository. Please make sure to update it on a regular basis – when new files or folder are added to the repository.
Give a brief explanation of what kind of contributions you are looking for and what your requirements are for accepting them. Then link to [CONTRIBUTING.md](link to your contributing.md file) for more information and also add a link to [CODE_OF_CONDUCT](link to your code_of_conduct.md file).
Adds names / GitHub profile links for those who have contributed to this repository. If you have a maintainer's list, link to it here.
Where can people ask for help: this can be any combination of an issue tracker,Slack, a chat room, an email address, etc.
If your project has a Slack, add it here, eg. "Click here and fill out the form to receive an invite to the [Project name] slack instance, to meet the community and learn more about how you can engage."[add link to Slack]
Example text: This project is licensed under the MIT License - see the LICENSE.md file for details.
(You can find the list of licenses approved for OASIS Open Projects here.)
Add a Hat tip to anyone whose work/code/project inspired your work.
A big Thank you for inspiration for this template goes to:
- the authors of Make a README
- @hackergrrl
- @matiassingers