Vincent A. Cicirello

Posted on Jul 15, 2022 • Edited on Jul 28, 2022

Badges - TL;DR for your repository's README

#github #tutorial #documentation #metadata

Before I began actively using GitHub to work on my research publicly, I would sometimes end up on GitHub looking for a tool to accomplish some task or looking for a relevant library, etc. My first take on badges at the top of the README of a repository was along the lines of "what is this nonsense?", and I'd proceed to ignore that section of the README entirely. The more I've used GitHub I've discovered that in repositories where that section is well-organized and the badges linked to relevant information that it serves a very useful purpose. Essentially, the right mix of relevant and dynamic badges, displaying the right metadata, and linked to the right information becomes a TL;DR for your README. And with dynamic badges, the metadata is always up to date for the visitors of your repository without any intervention on your part.

TL;DR: Well-organized badges with relevant links == TL;DR for a repository's README.

The remainder of this post is organized as follows:

What are badges?
Where do I get them?
Tips for using badges well
Repository Used in Examples
About Me

What are badges?

Here are a couple example badges from one of my projects, including how they are linked:

Without telling you anything you instantly know that the project publishes artifacts to Maven Central along with the latest version number, and you know the version of the latest GitHub release. If you follow the links, in the first case you end up on the Maven Central page for the library where you find all you need to import the library, and in the second case you end up on the releases tab of the GitHub repository.

Where do I get them?

There are three main sources of README badges: (1) badge generation services, (2) service specific badges, and (3) tools that you can run locally. Let's look at all three cases.

Badge generation services

Shields is probably the most widely used badge generation service. Another is Badgen. Shields has a larger variety with support for a wider variety of services, etc, but Badgen has a good variety as well, along with a few that Shields doesn't yet have. Most of these are dynamic badges, updating relevant information as things change (e.g., with new release version, build status, coverage percentage, etc). And both support both dynamic and static custom badges.

Service specific badges

Some services that you might use as part of your project may provide badges specific to their service. For example, if you use Zenodo to create DOIs for your releases, Zenodo provides a dynamic badge that updates with the DOI of the latest release, which you can link to the Zenodo archive of the release. Here is an example from the same project as above:

Snyk provides security score and vulnerability count badges, which you can link to the relevant pages, as in these examples:

Some badges may display static, yet still useful, metadata. For example, many of my repositories relate to my research, and as an academic also relate to journal articles I've published, such as an article in the Journal of Open Source Software, which provides each article with a badge that can be linked directly to the full-text of the article, such as:

Tools you can run yourself

In some cases, there may be tools that you can run yourself as part of your CI/CD workflows. For example, last week I posted about the jacoco-badge-generator, which can be used as either a GitHub Action or as a local CLI tool to parse a JaCoCo coverage report, generate coverage badges, as well as for performing PR checks. Here is a link to that DEV.to post:

The jacoco-badge-generator GitHub Action is now also available as a CLI tool from PyPI

Vincent A. Cicirello ・ Jul 8 '22

#java #github #kotlin #python

Tips for using badges well

If you just grab the URLs for all of the badges even remotely relevant to your repository from Shields or Badgen, and just haphazardly place them at the top of your README without linking them to anything, they may detract from the readability of your repository's README, rather than improving it. I have two tips related to using badges well to provide a TL;DR that is useful to the visitors of your repository, as well as to yourself and any collaborators, specifically organization and link to relevant information.

Tip 1: Organization

If your project only has need for a few badges, perhaps five or less, just putting them in a row is probably sufficient. But if your README has more than that, it is worth thinking a bit about how to organize them. I've seen a variety of approaches to this that are effective. The approach that I take is with a markdown table with one row for each category of badge. Here is an example from one of my repositories (the very case I've used earlier for a few examples). Note that this example table looks differently here on DEV.to than it does on GitHub. They appear to process tables differently. It looks better on GitHub (for the intended purpose of this table).

Publications About the Library
Packages and Releases
Build Status
JaCoCo Test Coverage
Security
DOI
License
Support

Is this the only way to organize this set of badges? Of course not. Is this the best way to do so? Probably not. I've rearranged stuff as I've added to it, or as I've used it. For example, the metadata isn't just for visitors to your repository. It is there for you too.

If you like the table approach, I recommend using bold on the row labels because GitHub-flavored markdown tables use bold by default on the header row assuming that it consists in column headings. If you don't bold the row labels, then only the top row will have a bold row label. I also recommend either explicitly left aligning the columns or centering the columns. The example above is left aligned. The reason is that GitHub-flavored markdown by default centers the column headings, but not the contents of the columns. So if you leave it to the default, only the top row will be centered. The structure that I use for left alignment is as follows, which looks better on GitHub than here on DEV for the purpose of organizing badges.



| __Category One__ | badge markup with links here |
| :--- | :--- |
| __Category Two__ | badge markup with links here |
| __Category Three__ | badge markup with links here |

Or if you want to center everything, the following should work:



| __Category One__ | badge markup with links here |
| :---: | :---: |
| __Category Two__ | badge markup with links here |
| __Category Three__ | badge markup with links here |

Tip 2: Every Badge Should Link to Something Relevant

Visitors to your repository will likely click on some of your badges, expecting to be taken to more detailed information related to the metadata displayed in the badge. In the example table above, every badge links to something relevant. For some of these, what to link to is obvious (e.g., package repository badges, release badges, license badges, among others). For a few, it is slightly less so. For example, for build status badges for builds run on GitHub Actions, it would be nice if it was possible to link directly to the specific workflow run that corresponds to the displayed status. As far as I'm aware, that is not possible, so in my example, I have that linked to the list of runs of the relevant workflow, although in the case of the status of building the docs, I link to the live API docs that I serve from GitHub Pages instead.

The markup to link a build status badge to the corresponding list of workflow runs is as follows:



[![ALTERNATE-TEXT](BADGE-URL-GOES-HERE)](https://github.com/USERID/REPO/actions/workflows/WORKFLOW-FILE-NAME.yml)

GitHub actually generates a status badge for each of your GitHub Actions workflows, with a URL of the form:



https://github.com/USERID/REPO/workflows/NAME-OF-YOUR-WORKFLOW/badge.svg

You can combine the above two with:



[![ALTERNATE-TEXT](https://github.com/USERID/REPO/workflows/NAME-OF-YOUR-WORKFLOW/badge.svg)](https://github.com/USERID/REPO/actions/workflows/WORKFLOW-FILE-NAME.yml)

Repository Used in Examples

If you want to look at the examples within the broader context, as well as to see the actual result of formatting as a table as it appears on GitHub, all examples in this post are from the following repository.

cicirello / Chips-n-Salsa

A Java library of Customizable, Hybridizable, Iterative, Parallel, Stochastic, and Self-Adaptive Local Search Algorithms

Chips-n-Salsa

Website: https://chips-n-salsa.cicirello.org/

API documentation: https://chips-n-salsa.cicirello.org/api/

Publications About the Library
Packages and Releases
Build Status
JaCoCo Test Coverage
Security
DOI
Other Information
Support

How to Cite

If you use this library in your research, please cite the following paper:

Cicirello, V. A., (2020). Chips-n-Salsa: A Java Library of Customizable, Hybridizable, Iterative, Parallel, Stochastic, and Self-Adaptive Local Search Algorithms. Journal of Open Source Software, 5(52), 2448, https://doi.org/10.21105/joss.02448 .

Overview

Chips-n-Salsa is a Java library of customizable, hybridizable, iterative, parallel, stochastic, and self-adaptive local search algorithms. The library includes implementations of several stochastic local search algorithms, including simulated annealing, hill climbers, as well as constructive search algorithms such as stochastic sampling. Chips-n-Salsa now also includes genetic algorithms as well as evolutionary algorithms more generally. The library very extensively supports simulated annealing. It includes several classes for representing solutions to a variety of optimization problems…

View on GitHub

About Me

Personal Website:

Vincent A. Cicirello - Professor of Computer Science

Vincent A. Cicirello - Professor of Computer Science at Stockton University - is a researcher in artificial intelligence, evolutionary computation, swarm intelligence, and computational intelligence, with a Ph.D. in Robotics from Carnegie Mellon University. He is an ACM Senior Member, IEEE Senior Member, AAAI Life Member, EAI Distinguished Member, and SIAM Member.

cicirello.org