This guide accompanies our README template. Please refer to these instructions for using the template.
What is your project, and why did you create it? You can help potential users—and contributors, if your project accepts contributions—understand the problem your project solves, and perhaps a bit of why you chose to the solve the problem in this way. This section should be fairly short (you’ll go into more detail below). For inspiration, check out Lazygit’s “Elevator pitch” section. You might also like to include a screenshot of your project in use!
Table of contents¶
A Table of Contents makes it easier for readers to find the information they’re looking for quickly! Feel free to add or delete sections below:
Features¶
What are the awesome things your project can do? You don’t need to list every feature (though you might, if your project is fairly small!), but you can list the standouts:
Feature 1
Feature 2
Feature 3
Getting Started¶
Prerequisites¶
What other software would a user need to have installed on their machine in order to use yours? Are there particular concepts they should already be familiar with?
dependency install command hereInstallation¶
How can users install your software? You might provide different methods for different package managers as well as different operating systems.
your project's install commandEnvironment variables (optional)¶
Perhaps an API is required to run your software, so you might say something like:
To run this project, you’ll need to add the following environment variables to your .env file:
API_KEY
ANOTHER_API_KEY
Running tests (optional)¶
If tests should be run, you can put the instructIons for that here.
test commandRun locally (optional)¶
Perhaps your users will run your project locally:
Clone the project:
git clone yourprojecturlGo to the project directory
cd my-projectInstall dependencies
install commandStart the server
server start commandDeployment (optional)¶
How is your software deployed?
deployment commandUsage¶
Use this space to document how to use your project. You might show additional screenshots, code samples, demos or link to other resources. If this section starts getting very long, consider setting up a dedicated wiki or docs site!
print("Hello, world!")Roadmap (optional)¶
Both users of and potential contributors to your project are likely to have ideas for possible features to add or other suggestions, and maintaining a roadmap will help keep everyone on the same page about plans for the project. You can create tables in Markdown, but you can also keep it simple:
Backlog¶
Research user needs for new product features
Develop initial product requirements document
To Do¶
Implement core feature set
Create technical architecture proposal
Identify key performance benchmarks
In Progress¶
Develop minimum viable product (MVP)
Set up continuous integration pipeline
Testing¶
Conduct alpha testing
Perform comprehensive security audits
Execute performance and load testing
Staged for Release¶
Finalize documentation
Done¶
Validate core product concept
Conduct user experience interviews
Contributing (optional)¶
If you’d appreciate contributions to your project, you might say something like:
Contributions are always welcome! Please see CONTRIBUTING.md for tips to get started.
Code of Conduct¶
If you’ll be accepting contributions to your project, you’ll need to consider how you’ll ensure a good experience for you and your contributors.
Please read check out the Code of Conduct for more detail!
FAQ (optional)¶
Any question you’ve been asked more than once (or suspect you’ll be asked more than once!) is a good candidate for an FAQ entry. And if you end up with more than a few FAQ entries, you’ll be ready to starting writing dedicated docs (stay tuned for help with that!)
Q: Question 1
Answer 1
Q: Question 2
Answer 2
License¶
Your license file should be in the root of your project’s repo, and you can link to it directly like this:
Distributed under the [insert your license name]. See LICENSE.txt for more information.
Contact (optional)¶
It’s up to you to decide how you’d like to be contacted with questions about your project! Common methods include:
Email address
Social media handle(s)
Link to your project’s forum, Slack channel, Discord server, etc.
Asking people to open an issue to ask their question
Attribution (optional)¶
Use this section to mention useful resources and libraries that you’ve leaned on in building your project. For example, we’re grateful to have built this template with inspiration from: