No matter what I tell you below, pick the badges that are most meaningful to your project. If you need badges for other services or custom ones get them from shields.io.
The version of your project and the software it relies on tells a lot about compatibility, if done right. All version numbers should use Semantic Versioning 2.0.0. It is the de-facto standard of open source projects. In case you don't follow these rules, don't bother to include a version badge, because it doesn't carry any meaning and can be deceptive.
Software typically only works with a specific operating system or device. Therefore it's a good idea to tell for which platform your code it intended. The word "platform" is great because it can describe software and hardware alike.
Automatic testing is the best way to prove that your code works as intended. If you use a testing service, make sure to include its badge! However as far as I can tell only the large and popular projects use automatic testing as it can take a lot of effort to set up.
Small projects with only a few contributors might not be updated for a long time, even if they are still in use. For those project consider adding a status badge. They are inspired by hackaday.io's "project status" feature and illustrate the main authors' intention toward the project.
Here's a small summary of the meaning of each value:
| value | description |
|---|---|
| active | The developers are working on new features, optimisations, documentation or another part of the project. The code will be kept in working condition by updating dependencies, fixing bugs and solving issues with a high priority. |
| maintained | The developers intend to keep the code in working condition by updating dependencies, fixing bugs and solving issues. |
| shelved | The developers paused most activity on this project, but intend to fix critical bugs and issues. The code may not work with the most recent dependencies. |
| legacy | The developers stopped working on this project, but the code remains usable in legacy applications. |
| deprecated | The developers stopped working on this project and do not recommend using it. It has been replace with: |
| scrapped | The developers stopped working on this project for significant issues and keep the code for archive purposes only. |
| research | The developers are experimenting with this project and therefore it might be highly unstable. Reports of issues and bugs are appreciated, but may take some time to solve. |
Provide context by linking the status badge to this readme or copy the following text into yours:
This project is currently classified as
--- description message here ---
No project is perfect, ever. Therefore it's quite important to know that questions will be answered and that broken things will be fixed. There isn't a single perfect metric, but you may want to pick one of the above.
Getting help and contributing is a fundamental part of open source. You can emphasise that you're open to pull requests, point to your favorite communication channel or highlight the popularity. For small projects these badges might be less useful.
If your license is incompatible to the one of a visitors' project, it is likely your code will be dismissed right there, not matter how good it is. The licenses listed above are used by the 200 most stared projects, the MIT license is by far the most common.
These badges are dynamically generated based on githubs data, their color indicates the compatibility level. If you have a non-standard license or offer multiple to choose from, consider adopting the style of the blue badge. I'd suggest that you add a link to the license section of your readme, but linking to the LICENSE.md is ok, too.
Badges in general follow the color scheme above. If you create new badges, try to align them with this or use other colors.