Progress / Percentage Badge

[Paebbels]

📋 Description

Note

Based on issue #3775, a new clean badge request with more specific requirements.

To visualize progress, a static progress/percentage badge would be helpful.

Usecases:

• Development progress
• Quality rating
  • undocumented, roughly documented, documented, excellently documented

Examples:

• From Can we support something like progressed.io? #3775 (comment)
  
  

🔗 Data

The data is provided by URL parameters. It's a generic shield.

Visualization options:

• Visualize a raw percentage (0..100%)
• Visualize a percentage based on numerator, denominator (0..100%)
• Select the color gradient:
  • red-green
  • green-red
  • red-yellow-green
  • green-yellow-red
  • user-defined?
• Visualize with typical shields.io styles, logo, label, ....
• If badge content is empty, the percentage is shown with %-sign.
  Otherwise, the badge content is shown.

URL parameters:

• ?....&percentage=XX&...., where XX is 0..100 (integer) or 0.00..1.00 (real)
• ?....&numerator=XX&denominator=YY&...., where XX is any positive integer 0..∞ and YY is any positive integer 1..∞
• ?....&gradient=XX&...., where XX is
  • red-green, 0 is red, 100 is green
  • green-red, 0 is green, 100 is red
  • red-yellow-green, 0 is red, 50 is yellow, 100 is green
  • green-yellow-red, 0 is green, 50 is yellow, 100 is red
  • YYYY1-YYYY2-....-YYYYN, 0 is YYYY1, .... 100 is YYYYN, where NNNN might be a CSS color name or hex-color code.
    The gradient is equally distributed into N equally sized portions. In case users want a larger yellow section, yellow could be repeated like red-yellow-yellow-green.
    Is - a good sepertor between color names?

🎤 Motivation

Shields.io has a generic shield allowing to handled lots of shield use cases, that aren't provided by a data source. This is already awesome for text related use cases.

Besides text, some shields offer a gradient coloring like in code coverage or programming style ratings. Unfortunately, such a colored rating isn't available as a generic shield, where a user can provide a percentage or fraction, which gets translated to a color within a color gradient range.

[Paebbels]

Looking at all badges offered by Shields.io, I saw "new" dynamic badges. I was not aware of these new options. I use shield.io since years, but didn't check for new options.

Anyhow, on a second thought, maybe shields.io isn't missing a second static badge type, but an extension to static (and dynamic?) badges, which offers the proposed possibility to derive the color from a color gradient based on a percentage instead of a fixed color.

---

Note

Maybe shield.io could announce new features by writing a release page, then all watching users get notification emails :)

[PyvesB]

The badges shown in the example can be trivially created via the static badge, for example https://img.shields.io/badge/-95%25-green. Aside from the static badge and the Twitter exception, Shields.io doesn't host badges that don't show dynamic information.

My understanding of #3775 and #3932 is that folks wanted some sort of "progress bars" that would be non-text-based. To me it was about creating a new visual.

Does anyone have a screenshot of what progressed.io looked like? I feel it would help clear up a lot of the misalignment here :)

[Paebbels]

The badges shown in the example can be trivially created via the static badge, for example https://img.shields.io/badge/-95%25-green.

Not all of it. It can generate the text 95%, but the color gradient can't be computed. This requires dynamic code to compute the fraction and to compute the color code from that fraction.

Does anyone have a screenshot of what progressed.io looked like?

I checked https://web.archive.org/ for progressed.io, but it only lists broken results. I checked multiple days in multiple years, but couldn't find any valid content.

To me it was about creating a new visual.

Just in theory, would we talk about a variable boundary between label and content, where the color boundary at 0% shows just the content color and at 100%, it shows the label color?

Or: is the progress just within the content parts of a label, keeping a label readable?

I created a mockup (Paint :)):

[PyvesB]

Not all of it. It can generate the text 95%, but the color gradient can't be computed. This requires dynamic code to compute the fraction and to compute the color code from that fraction.

Just to be sure we're on the same page about this, the gradients we use for things like coverage percentages are discrete buckets, we don't do any fractional continuous color computation:

shields/services/color-formatters.js

Lines 64 to 76 in b106f36

	function floorCount(value, yellow, yellowgreen, green) {
	if (value <= 0) {
	return 'red'
	} else if (value < yellow) {
	return 'yellow'
	} else if (value < yellowgreen) {
	return 'yellowgreen'
	} else if (value < green) {
	return 'green'
	} else {
	return 'brightgreen'
	}
	}

Anything between 90 and 100% (excluded) will lead to the same static . There are only five colors in total.

I created a mockup (Paint :)):

I've got no clue whether this is what progressed.io looked like or if it's what others wanted, but the Paint skills are very much appreciated :)

[Paebbels]

[...] we use for things like coverage percentages are discrete buckets [...]

Ah I see. Is this "color gradient" accessible by the user or is it only available for certain service like code coverage? If so, then it would be nice if this logic would be accessible for the static and dynamic badge feature.

[PyvesB]

Only available for some services!

Related discussion: #9628

[heliocarlitos]

I created a web version based on this library that allows you to create and customize GitHub statistics for a clean, organized, and professional README, without needing to write any code.

This tool is especially useful for those starting on GitHub or who have difficulty understanding documentation but want to improve their profile presentation.

Access the Application

https://nice-readme.vercel.app/

Main Features

1. Readme Streak Stats

Displays daily contribution streaks on GitHub, promoting consistency, discipline, and visual motivation directly in the public README.
https://nice-readme.vercel.app/streak-stats

2. Git Readme Stats

Shows general GitHub statistics, such as the number of commits, repositories, and most-used languages, allowing quick analysis of user activity.
https://nice-readme.vercel.app/github-stats

3. Pins

Allows you to pin relevant projects in the README, highlighting priority repositories and facilitating access to important work.
https://nice-readme.vercel.app/repo-pins

4. Badges

Provides informative and customizable badges for technologies, statuses, and metrics, improving visual communication and the credibility of your GitHub profile.
https://nice-readme.vercel.app/badges