DEV Community

Dan
Dan

Posted on • Originally published at pixelbrackets.de

Awesome Open Source Badges for your Git README

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:

[![Latest Version](https://img.shields.io/github/v/tag/<USER>/<REPOSITORY>?sort=semver&label=version)](https://github.com/<USER>/<REPOSITORY>/)
Enter fullscreen mode Exit fullscreen mode

Latest Version

From Packagist tags:

[![Latest Version](https://img.shields.io/packagist/v/<USER>/<PACKAGE>?label=version)](https://packagist.org/packages/<USER>/<PACKAGE>/)
Enter fullscreen mode Exit fullscreen mode

Latest Version

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:

[![Development Branch](https://img.shields.io/badge/development_branch-<DEVELOPMENT BRANCH>-green.svg)](https://github.com/<USER>/<REPOSITORY>/tree/<DEVELOPMENT BRANCH>/)
Enter fullscreen mode Exit fullscreen mode

Development Branch

From GitHub release page:

[![Commits in development](https://img.shields.io/github/commits-since/<USER>/<REPOSITORY>/latest/)](https://github.com/<USER>/<REPOSITORY>/tree/<DEVELOPMENT BRANCH>/)
Enter fullscreen mode Exit fullscreen mode

Commits in development

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:

[![Build Status](https://img.shields.io/github/workflow/status/<USER>/<REPOSITORY>/<WORKFLOW>?label=build)](https://github.com/<USER>/<REPOSITORY>/actions)
Enter fullscreen mode Exit fullscreen mode

Build Status

Programming language

Show the language which is used in the package.

Manual:

[![Made With](https://img.shields.io/badge/made_with-php-blue)](/docs/requirements/)
Enter fullscreen mode Exit fullscreen mode

Made With

[![Made With](https://img.shields.io/badge/%3C%2F%3E-PHP%2C%20JavaScript-blue)](/docs/requirements/)
Enter fullscreen mode Exit fullscreen mode

Made With

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:

[![Packagist](https://img.shields.io/packagist/v/<USER>/<PACKAGE>)](https://packagist.org/packages/<USER>/<PACKAGE>/)
Enter fullscreen mode Exit fullscreen mode

Packagist

From Packagist download counter:

[![Packagist Downloads](https://img.shields.io/packagist/dm/<USER>/<PACKAGE>.svg?label=packagist%20downloads)](https://packagist.org/packages/<USER>/<PACKAGE>)
Enter fullscreen mode Exit fullscreen mode

Packagist Downloads

Some package repositories support showing ratings instead. This is not possible for Packagist yet.

Documentation

Documentation is key! Provide quick access to documentation.

Manual:

[![Development Branch](https://img.shields.io/badge/docs-<TYPE>-green.svg)](https://github.com/<USER>/<REPOSITORY>/blob/master/<DOC FILE>/)
Enter fullscreen mode Exit fullscreen mode

Development Branch

From Read the Docs:

[![Documentation Status](https://img.shields.io/readthedocs/<PROJECT>)](https://<PROJECT>.readthedocs.io/)
Enter fullscreen mode Exit fullscreen mode

Documentation Status

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:

[![License](https://img.shields.io/badge/license-mit-blue.svg)](https://github.com/<USER>/<REPOSITORY>/blob/master/<LICENSE FILE>)
Enter fullscreen mode Exit fullscreen mode

License

[![License](https://img.shields.io/badge/license-gpl--2.0--or--later-blue.svg)](https://spdx.org/licenses/GPL-2.0-or-later.html)
Enter fullscreen mode Exit fullscreen mode

License

[![License](https://img.shields.io/badge/license-cc_by--sa_3.0-blue.svg)](https://creativecommons.org/licenses/by-sa/3.0)
Enter fullscreen mode Exit fullscreen mode

License

From Packagist manifest:

[![License](https://img.shields.io/packagist/l/<USER>/<PACKAGE>.svg)](https://github.com/<USER>/<REPOSITORY>/blob/master/<LICENSE FILE>)
Enter fullscreen mode Exit fullscreen mode

License

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:

[![Contribution](https://img.shields.io/badge/-help_wanted-brightgreen.svg)](https://github.com/<USER>/<REPOSITORY>/blob/master/<CONTRIBUTION FILE>)
Enter fullscreen mode Exit fullscreen mode

Contribution

[![Contribution](https://img.shields.io/badge/-contributions_welcome-brightgreen.svg)](https://github.com/<USER>/<REPOSITORY>/blob/master/<CONTRIBUTION FILE>)
Enter fullscreen mode Exit fullscreen mode

Contribution

From GitHub contributors counter:

[![Contributors](https://img.shields.io/github/contributors/<USER>/<REPOSITORY>.svg)](https://gitHub.com/<USER>/<REPOSITORY>/graphs/contributors/)
Enter fullscreen mode Exit fullscreen mode

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.

[![First Timers Friendly](https://img.shields.io/badge/first--timers--only-friendly-blue.svg)](https://github.com/<USER>/<REPOSITORY>/labels/contribute)
Enter fullscreen mode Exit fullscreen mode

First Timers Friendly

Code of Conduct

Show all contributors and maintainers of a project the common interest in an open and welcoming community.

Manual:

[![Code of Conduct](https://img.shields.io/badge/code_of_conduct-🌐-ff69b4.svg?logoColor=white)](https://github.com/<USER>/<REPOSITORY>/blob/master/<CONTRIBUTION FILE>)
Enter fullscreen mode Exit fullscreen mode

Code of Conduct

A popular code of conduct template is the Contributor Covenant.

[![Code of Conduct](https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg)](<CODE OF CONDUCT FILE>)
Enter fullscreen mode Exit fullscreen mode

Code of Conduct

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.

[![Discussion](https://img.shields.io/gitter/room/<USER>/<PROJECT>.svg)](https://gitter.im/<USER>/<PROJECT>)
Enter fullscreen mode Exit fullscreen mode

Discussion

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:

[![Funding](https://img.shields.io/badge/donations-welcome-yellow.svg)](https://github.com/<USER>/<REPOSITORY>/blob/master/FUNDING.yml)
Enter fullscreen mode Exit fullscreen mode

Funding

From Liberapay:

[![Funding](https://img.shields.io/liberapay/patrons/<PROJECT>.svg)](https://liberapay.com/<PROJECT>/donate)
Enter fullscreen mode Exit fullscreen mode

Funding

From Open Collective:

[![Funding](https://img.shields.io/opencollective/all/<PROJECT>.svg)](https://opencollective.com/<USER>)
Enter fullscreen mode Exit fullscreen mode

Funding

<3 Open Source

Spread the love for Open Source.

Manual:

[![Open Source Software](https://img.shields.io/badge/open_source-🤍-3DA639.svg)](https://opensource.org/)
Enter fullscreen mode Exit fullscreen mode

Open Source Software

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.

[![Say Thanks](https://img.shields.io/badge/say-thanks-ff69b4.svg)](https://saythanks.io/to/<USER>)
Enter fullscreen mode Exit fullscreen mode

Say Thanks

Generic custom badges

If you want add any more information, then use a custom badge.

[![TOPIC](https://img.shields.io/badge/<TOPIC>-<STATUS>-<COLOR>.svg)](https://example.com/)
Enter fullscreen mode Exit fullscreen mode

TOPIC

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>

Top comments (0)