Skip to main content

Template

Below is a template README for NiT projects. It is a welcome message to potential collaborators. Not all projects follow this structure but it is encouraged that they have some kind of structure that communicates the goals of the project as well as how someone can help contribute to that project.

Meta​

Many libraries add badges that show the status of the build or other meta information about the project. Add these at the top to help give details about the state of the project from CI/CD builds or other badging libraries.

Further reading:

  • shields.io
  • badges

Intro​

The introduction should summarize and capture the purpose of the project. Questions you might want to answer here are:

  • What problem does this project solve?
  • How does this project help people?
  • What inspired you to build this project?
  • Who helped you build this project?
  • Where did you take inspiration from to build this project?
  • What tools were involved in building the project?

This provides much needed context for the decisions you have made and will help observers or contributors to better empathize with those decisions.

Usage​

The usage covers how the library and/or web application can be used. For example, is it as simple as visiting the website? If so, then mention that. If more directions are required to get it working then go through that usage in detail. In projects that are libraries, you might want to create an examples folder to provide more recipes of how to use it.

Status​

When anyone first comes to a repo they are curious what the current state of the project is. Here you can inform them whether the project is maintained or unmaintained, who it is maintained by, and how someone can get in touch with the maintainer, whether through social media, email, or submitting an issue and tagging them in it. From here the person can see how they might want to get involved in case they are interested in becoming a maintainer or supporting a maintainer.

Contributing​

There are contributors of various degrees on any project. There are people that only help with documentation, fix typos, or make significant additions to the codebase. But in general, they want to know how they can contribute. This is where having a GitHub project outlining the goals of the project or a road map for future releases is really important. Don't keep all the innovative ideas of the project in your head. Get them in the README or in the issues in order to help direct people to actionable tasks instead of having them look in several places. In this case, you may want to remove the ability for someone to make an issue and instead have them email you the issue instead. This can help you, and others, stay focused on collaboration and the goals of the road map and not be side tracked by suggestions from those who don't want to help or who do not have the time to help. Either way, get the goals in a markdown file and educate people on how they can help with well written tasks that anyone can work on. You may want to add this to a CONTRIBUTING.md file.

Contributors​

Use the all-contributors bot to recognize the work of everyone in the project, especially those who do not make changes to the codebase. Anyone can make contributions to help improve the project and we appreciate all who do.

Further reading:

  • all-contributors

Code of Conduct​

This is a sacred space. We expect everyone to behave in a respectful manner. Always include a CODE_OF_CONDUCT.md file so that everyone is aware of desired behavior. Undesired behavior will not be tolerated and action will be taken if misconduct continues unabated.

Further reading:

  • Add a CoC to your GitHub project

License​

The license of a project speaks to how the project can be used. This is important for those who work in open source. They want to know they are contributing to a project that can be freely distributed. In most cases, having an MIT license would suffice. However, if this is not the case then make sure you spend the time finding a license that works for your use case.

Further reading:

  • OSS Licenses