You may have seen badges in READMEs of different repos - maybe in Github, Gitlab or Bitbucket. You may have also wondered why people are embedding them in their repos and how could they be helpful to users. If so, this is the right place for you.
Others also welcome to read as this could contain some valuable stuff
There are many reasons people adding badges to their README.
- Because they are visaully appealing
- Because they provide information simply and sweetly and quickly
Usually repos with badges attract users more than projects without badges in their README. Badges are a good way to show your colours and the quality of your product. Also it gives a pleasant view to your users.
Most importantly, they can communicate the information of your project very quickly. People usually display their project's build status, coverage reports, documentation, social status quickly using the badges.
Here are the things that I found as the most essential badges to include in your repo.
Build status
This tells us about how the current project base performed in the CI pipelines and tests of different kinds - you may include many reasons as possible. Generally most of the CI providers give you a nice looking badge to include in your README. Here are some examples
It is better if you could insert the corresponding link for every badge you insert
Code coverage
Code coverage tells the performance of the tests created simply. It checks for lines and statements covered by statements to create the coverage reports. Many coverage report providers give you another badge to include in your repository (codecov and coveralls are 2 providers that I personally like)
Code quality
Code quality is another important thing to maintain a long-term project. It allows people not to mix styles and make a complete mess. It also helps to avoid mistakes we often do in programming.
License
A good way to catch the user's attention to license is creating a badge. There are many ways to include badges about license and I found shields.io as the easiest.
You can simply create the badge you want by filling the relevant details there.
https://shields.io/category/license
Social status
If you are looking for people to contribute your project more often, the best way is to keep social. Social status badges enforces your users to see the social status of you and your projects and will also help you to catch contributors to other projects as well. There are many categories under this. This may also include donation links. Following are the most important things for me. I'm using shields.io for this one as well.
Follow the link
- Github stars
- Github followers
- Github forks
- Twitter followers
- Open collective backers
- First timers only
There could be more and more reasons to add badges to your repo. Let me know if you found more.
PS: I'm using shields.io to make awesome badges. You may also try it
PS++: I'm new to blogging. So please let me know if I doing something wrong
Top comments (4)
I'd like to emphasize repostatus from repostatus.org which is an easy and direct way to communicate, whether a repo is maintained, work in progress, abandoned etc.
Yes, I have also heard of that. Maintainability is also another important factor for new contributors. Thanks for reminding me about that. I'll add that soon (within next 24 hours 😁)
100% code coverage is usually overzealous. Especially if the repo in question is executable and not a library.
I got that badge from a repo of mine (which is a library). Actually the coverage is about 99.7% but shields.io have rounded that value. Getting 100% coverage for a repo is hard - especially if it is too big - the not impossible