Description: A few sentences about your project and/or overview that explains what your project is about.
Build status of continuous integration (travis, appveyor, etc.) and code style (xo, standard etc.). It's common to include status badges here so contributors and prospective end-users can see the status of your project at a glance. Just don't go too crazy or it will look like a mess.
Find status badges at the follow sites:
Depending on how long the
READMEis, add in a ToC or even abstract some sections away to different markdown files (i.e.CONTRIBUTING.md,USAGE.md, etc.).
Include logo, demo, screenshot etc.
What makes your project stand out? What pain points does it solve for the prospective user? Compare it to competitor apps/tools to show how it is different/better.
Show what your code does as concisely as possible. Users should be able to figure out how your project solves their problem by looking at the example. Also include the example code as a file in your repo (named
example.jsor in anexampledirectory) so that users can run the code if they clone down the repository.
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.
List which technologies the user needs to install the software and how to install these dependencies.
Links to resources and installation instructions. Include code examples. Break instructions down by operating system if necessary.
This section tells the user how to get a local environment running. Be sure to include specific step-by-step instructions for the installation process to accommodate coders of all levels. This section will vary greatly depending on the type of code the repository contains. For example, a Node package is usually installed by typing
npm install <package-name>in the terminal, whereas other projects you may have to fork and clone down the repository. In both cases the user needs to have the requisite technology installed to run to code. Even with a Docker image, the user still needs to be able to run Docker on their machine. Keep this in mind when writing out the "Prerequisites" and "Installation" sections.
Depending on the size of the project, if it is small and simple enough the reference docs can be added to the
README. For medium size to larger projects it is important to at least provide a link to where the API reference docs live.
Explain how to run the automated tests for this system.
Explain what these tests test and why. Include code examples.
Explain what these tests test and why. Include code examples.
Add additional notes about how to deploy this on a live system.
End with an example of getting some seed data out of the system or using it for a demo. Add screenshots, video links, and/or GIFs in this section to make your usage instructions as clear as possible to the user.
List of tech languages, frameworks/libraries, and tools used
- [Language](link to language documentation)
- [Framework](link to framework documentation)
- [Database](link to database documentation)
A short description of the motivation behind the creation and maintenance of the project. This should explain why the project exists.
Add more detailed instructions for open-source projects. It's a good idea to include a code of conduct as well as resource links as to where absolute beginners can go to learn how to contribute to open source. Here's a great place to start. I personally like the Contributor Covenant and use the below statement as my default. I intend to expand on it once I create an open-source project truly worthy of others' contributions.
Issues and pull requests are welcome at . This project as well as all other content on my GitHub are intended to be safe, welcoming, and open for collaboration. Users are expected to adhere to the Contributor Covenant code of conduct and those that do not will be reported and blocked. I got no time for that nonsense.
Include your name and any links to your social media, contact info, or websites that you'd like. Don't forget to s/o your contributors here too!
See also the list of contributors who participated in this project.
Add a list of contributors here. You may want to feature some who have really stood out.
- Hat tip to anyone whose code was used
- Inspiration
- Anything else that seems useful
Include your license here. This is an absolute must as some users require that all services they include in their project have a license that matches their own. The MIT License is GitHub's recommendation and probably the most common one you'll see in repos, but there are other options available—copyleft, anybody?—and that's not even an exhaustive list, just the most popular licenses on GitHub.
This project is licensed under the MIT License - see the LICENSE.md file for details.
- A Beginner's Guide to Writing a Kickass README: A short and sweet summary with many examples at the end.
- Art of README: An informational repo on the what and why behind
READMEs.
- Standard README: I like the simplicity with the extensive use of links.
- Open-Source Template: Figured I'd throw this in here in case it comes in handy for anyone.
- Awesome README: Another Awesome List—
READMEEdition.
- Choose an Open Source License: A non-exhaustive list of licenses curated by GitHub.
- Searching GitHub by License Type: You can filter repositories based on their license or license family using the
licensequalifier and the exact license keyword - The Legal Side of Open Source: Everything you've ever wondered about the legal side of open source, and a few things you didn't.
- Open Source Guides: Open source software is made by people just like you. Learn how to launch and grow your project.
Thank you, Meg. I forked this to use going forward.