Awesome Open Source Badges for your Git README
Tags: badges, readme, opensource, shields
Published: 2020-09-26 14:14:23

---
title: Awesome Open Source Badges for your Git README
published: true
description: Badges are a pretty way to display concise project information in a README.
tags: badges, readme, opensource, shields
---

**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](https://shields.io). 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>/)

[![Latest Version](https://img.shields.io/github/v/tag/guzzle/guzzle?sort=semver&label=version)](https://github.com/guzzle/guzzle/)

From Packagist tags:

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

[![Latest Version](https://img.shields.io/packagist/v/guzzlehttp/guzzle?label=version)](https://packagist.org/packages/guzzlehttp/guzzle/)

The link could point to a [release page](https://github.com/guzzle/guzzle/releases), [Packagist](https://packagist.org/packages/guzzlehttp/guzzle) or a [Changelog file](https://github.com/guzzle/guzzle/blob/master/CHANGELOG.md).

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

![Development Branch](https://img.shields.io/badge/development_branch-next--release-green.svg)

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

[![Commits in development](https://img.shields.io/github/commits-since/guzzle/guzzle/latest/)](https://github.com/guzzle/guzzle/tree/master/)

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)

[![Build Status](https://img.shields.io/github/workflow/status/guzzle/guzzle/CI?label=build)](https://github.com/guzzle/guzzle/actions?query=workflow%3ACI)

## 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/made_with-php-blue)](/docs/requirements/)

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

[![Packagist](https://img.shields.io/packagist/v/guzzlehttp/guzzle)](https://packagist.org/packages/guzzlehttp/guzzle/)

From Packagist download counter:

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

[![Packagist Downloads](https://img.shields.io/packagist/dm/guzzlehttp/guzzle.svg?label=packagist%20downloads)](https://packagist.org/packages/guzzlehttp/guzzle)

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

[![Development Branch](https://img.shields.io/badge/docs-quickstart-green.svg)](https://github.com/guzzle/guzzle/blob/master/docs/quickstart.rst)

From Read the Docs:

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

[![Documentation Status](https://img.shields.io/readthedocs/guzzle)](https://guzzle.readthedocs.io/)

Hint: A nice service is [Inch CI](https://inch-ci.org/learn_more), 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-mit-blue.svg)](https://github.com/guzzle/guzzle/blob/master/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)

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

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

[![License](https://img.shields.io/packagist/l/guzzlehttp/guzzle.svg)](https://github.com/guzzle/guzzle/blob/master/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>)

[![Contribution](https://img.shields.io/badge/-help_wanted-brightgreen.svg)](https://github.com/sebastianbergmann/phpunit/blob/master/.github/CONTRIBUTING.md)

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

[![Contribution](https://img.shields.io/badge/-contributions_welcome-brightgreen.svg)](https://github.com/sebastianbergmann/phpunit/blob/master/.github/CONTRIBUTING.md)

From GitHub contributors counter:

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

[![Contributors](https://img.shields.io/github/contributors/guzzle/guzzle.svg)](https://gitHub.com/guzzle/guzzle/graphs/contributors/)

Another nice way to encourage contributions is the [First Timers Friendly](https://www.firsttimersonly.com/) 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)

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

[![Code of Conduct](https://img.shields.io/badge/code_of_conduct-🌐-ff69b4.svg?logoColor=white)](https://github.com/sebastianbergmann/phpunit/blob/master/.github/CODE_OF_CONDUCT.md)

A popular code of conduct template is the [Contributor Covenant](https://www.contributor-covenant.org/).

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

[![Code of Conduct](https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg)](https://www.contributor-covenant.org/)

## 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](https://gitter.im/) 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>)

[![Discussion](https://img.shields.io/gitter/room/guzzle/guzzle.svg)](https://gitter.im/guzzle/guzzle)

An alternative is a message board or linking to tags on [Stack Overflow](https://stackoverflow.com/).

## 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](https://help.github.com/en/github/administering-a-repository/displaying-a-sponsor-button-in-your-repository).

Manual:

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

[![Funding](https://img.shields.io/badge/donations-welcome-yellow.svg)](https://github.com/sebastianbergmann/phpunit/blob/master/.github/FUNDING.yml)

From Liberapay:

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

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

From Open Collective:

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

[![Funding](https://img.shields.io/opencollective/all/symfony-diversity-scholarship.svg)](https://opencollective.com/symfony-diversity-scholarship)

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

[![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](https://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>)

[![Say Thanks](https://img.shields.io/badge/say-thanks-ff69b4.svg)](https://saythanks.io/to/kennethreitz)

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

[![TOPIC](https://img.shields.io/badge/topic-status-green.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](https://simpleicons.org/): `?logo=<NAME>`