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.
- Project Logo (optional)
- Project Title
- Badges (optional)
- Introduction
- Getting Started
- Installation
- How to run tests(optional)
- Deployment
- Built With
- Contributing
- Versioning
- 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 possible, include screenshots and demo videos.
These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.
If applicable, list here what is need to install the software and how to install them. Also list any dependencies, if applicable.
A step by step series of examples that tell you how to get a development env running
Say what the step will be
Give the example
And repeat
until finished
End with an example of getting some data out of the system or using it for a little demo
Explain how to run the automated tests for this system
Give an example
Add additional notes about how to deploy this on a live system
List any libraries, frameworks or other projects that your code might be using
Add a brief explanation of what kind of contributions you are looking for and what your requirements are for accepting them. Add a link to [CONTRIBUTING.md](link to your contributing.md file) and a link to [CODE_OF_CONDUCT](link to your code_of_conduct.md file).
List authors and maintainers here, e.g.: *
And/or: "See also the list of contributors who participated in this project."
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]
This project is licensed under the Apache 2.0 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 code was used or projects that inspire your work etc.