pixelbrackets
tl;dr Badges are a pretty way to display concise project information in a README.
Badges are a pretty way to display concise information about a project. They consist of a small image showing a topic and a status message and optionally linking to further information. Like tags they written in lowercase. Usually they are added to the top of a README file, which should contain sections for the topics anyway.
The most popular badge service is Shields. They allow custom badges and provide a huge list of dynamic badges. The later gather additional data from other services like code style checkers or download trackers. And a very big advantage is their »no tracking« policy.
In this post I will show a couple of badges you may consider adding to your Open Source package. The examples refer to GitHub and PHP/Packagist, but there are equivalents for most languages and plattforms.
Latest Version
Show the latest release of the package.
From GitHub tags:
[](https://github.com/<USER>/<REPOSITORY>/)
From Packagist tags:
[](https://packagist.org/packages/<USER>/<PACKAGE>/)
The link could point to a release page, Packagist or a Changelog file.
Development
Show in which branch the development is done or how many commits since the latest release are added.
Manual:
[](https://github.com/<USER>/<REPOSITORY>/tree/<DEVELOPMENT BRANCH>/)
From GitHub release page:
[](https://github.com/<USER>/<REPOSITORY>/tree/<DEVELOPMENT BRANCH>/)
The link could point to the development branch or a milestone page.
Latest Build Status
Show the latest CI pipeline result.
From GitHub CI workflow:
[](https://github.com/<USER>/<REPOSITORY>/actions)
Programming language
Show the language which is used in the package.
Manual:
[](/docs/requirements/)
[](/docs/requirements/)
The link could point to an installation guide or requirements section in your README.
Package Repository
Show where to get the package (Packagist, NPM, RubyGems etc).
This may be combined with the version badge. So this could show some statistics instead.
From Packagist:
[](https://packagist.org/packages/<USER>/<PACKAGE>/)
From Packagist download counter:
[](https://packagist.org/packages/<USER>/<PACKAGE>)
Some package repositories support showing ratings instead. This is not possible for Packagist yet.
Documentation
Documentation is key! Provide quick access to documentation.
Manual:
[](https://github.com/<USER>/<REPOSITORY>/blob/master/<DOC FILE>/)
From Read the Docs:
[](https://<PROJECT>.readthedocs.io/)
Hint: A nice service is Inch CI, which measures how code is documented and shows the result in a badge. Currently supports JavaScript and Ruby only though.
License
Show the license of the package. This is crucial while researching compatible packages.
Manual:
[](https://github.com/<USER>/<REPOSITORY>/blob/master/<LICENSE FILE>)
[](https://spdx.org/licenses/GPL-2.0-or-later.html)
[](https://creativecommons.org/licenses/by-sa/3.0)
From Packagist manifest:
[](https://github.com/<USER>/<REPOSITORY>/blob/master/<LICENSE FILE>)
Contribution
A great part of Open Source is the possibility to let people contribute. Show contributers how to do so and add a link to a contribution guide.
Manual flags:
[](https://github.com/<USER>/<REPOSITORY>/blob/master/<CONTRIBUTION FILE>)
[](https://github.com/<USER>/<REPOSITORY>/blob/master/<CONTRIBUTION FILE>)
From GitHub contributors counter:
[](https://gitHub.com/<USER>/<REPOSITORY>/graphs/contributors/)
Another nice way to encourage contributions is the First Timers Friendly badge and a link to issues tagged with first-timers-only or contribute.
[](https://github.com/<USER>/<REPOSITORY>/labels/contribute)
Code of Conduct
Show all contributors and maintainers of a project the common interest in an open and welcoming community.
Manual:
[](https://github.com/<USER>/<REPOSITORY>/blob/master/<CONTRIBUTION FILE>)
A popular code of conduct template is the Contributor Covenant.
[](<CODE OF CONDUCT FILE>)
Metrics
Show some metrics like security, dependencies, test coverage, code climate.
Discussion
Provide a place where users may discuss how to use the package or fix issues.
A popular service is Gitter by GitLab. They provide a public chat for any repository. Users need no invitation link and dont need to sign up.
[](https://gitter.im/<USER>/<PROJECT>)
An alternative is a message board or linking to tags on Stack Overflow.
Funding
Show people how to they may support the project financially with donations, sponsorships or subscriptions.
GitHub allows to add several funding plattforms trough a FUNDING.yml.
Manual:
[](https://github.com/<USER>/<REPOSITORY>/blob/master/FUNDING.yml)
From Liberapay:
[](https://liberapay.com/<PROJECT>/donate)
From Open Collective:
[](https://opencollective.com/<USER>)
<3 Open Source
Spread the love for Open Source.
Manual:
[](https://opensource.org/)
Maybe you want to add a link to SayThanks.io, a project which encourages users to send a simple “thank you“ note to creators of an Open Source package.
[](https://saythanks.io/to/<USER>)
Generic custom badges
If you want add any more information, then use a custom badge.
[](https://example.com/)
Overwrite dynamic badges
You may override the labels, colors and style of all badges by adding some parameter as described in the Shields documentation.
- Change title:
?label=<TITLE> - Change color:
?color=<HEX> - Change style:
?style=flat-square - Add an icon from Simple Icons:
?logo=<NAME>