Awesome Open Source Badges for your Git README

Dan — Sat, 26 Sep 2020 14:14:23 +0000

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>/)

From Packagist tags:

[![Latest Version](https://img.shields.io/packagist/v/<USER>/<PACKAGE>?label=version)](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:

[![Development Branch](https://img.shields.io/badge/development_branch-<DEVELOPMENT BRANCH>-green.svg)](https://github.com/<USER>/<REPOSITORY>/tree/<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>/)

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)

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/)

[![Made With](https://img.shields.io/badge/%3C%2F%3E-PHP%2C%20JavaScript-blue)](/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:

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

From Packagist download counter:

[![Packagist Downloads](https://img.shields.io/packagist/dm/<USER>/<PACKAGE>.svg?label=packagist%20downloads)](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:

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

From Read the Docs:

[![Documentation Status](https://img.shields.io/readthedocs/<PROJECT>)](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:

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

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

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

From Packagist manifest:

[![License](https://img.shields.io/packagist/l/<USER>/<PACKAGE>.svg)](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:

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

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

From GitHub contributors counter:

[![Contributors](https://img.shields.io/github/contributors/<USER>/<REPOSITORY>.svg)](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.

[![First Timers Friendly](https://img.shields.io/badge/first--timers--only-friendly-blue.svg)](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:

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

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>)

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>)

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)

From Liberapay:

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

From Open Collective:

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

<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/)

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>)

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/)

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>

DEV Community: Dan

Awesome Open Source Badges for your Git README

Latest Version

Development

Latest Build Status

Programming language

Package Repository

Documentation

License

Contribution

Code of Conduct

Metrics

Discussion

Funding

<3 Open Source

Generic custom badges

Overwrite dynamic badges