Shields: Remove the popout badge formats?

[paulmelnikow]

I think the popout badge formats look cool, and that it is possible to arrange them side-by-side in readmes in a way that looks good, and that they could even be used to convey useful information like distinguishing one platform for another (you could argue that logo + text does this better than text).

However, I don't think they are used very often. We've also gotten a complaint about them from one of the founders of shields, on the basis that consistency is a goal of the project, and offering lots of formats works against that. (#1478)

I certainly don't feel very strongly about them, one way or another.

However, I was in the process of working on #2428 (which I lost steam on a couple months ago) and wasn't personally feeling it was necessarily worth the effort to maintain these formats. So I thought I would raise the question. Would anyone be upset if we dropped these formats?

I don't think we have stats on the badge formats, though perhaps we should turn that on for a few days to inform this question.

[calebcartwright]

Would anyone be upset if we dropped these formats

I assume this question is directed to everyone (Shields end users, contributors, maintainers, etc.) correct? I don't feel strongly either. I don't use the popout format myself.

[paulmelnikow]

Shields end users, contributors, maintainers, etc.

Yes, to everyone. 😁

I mean, if there's one person who wants to use it that probably is not enough to justify keeping it. It's not terribly hard to put something like RunKit in front of the Shields JSON badge, for a small number of people who are really passionate. But if I'm wrong and it's actually really popular, or really important to a significant group of maintainers or contributors, that could be reason to keep it.

[PyvesB]

I don't have any strong opinions on this myself. Do we have any precise usage statistics? I've pinned the issue in an attempt to gather more feedback from our users.

[paulmelnikow]

I agree it would be helpful to collect usage statistics.

[chris48s]

One thing to consider when you collect stats:
For some reason (copy+pasteing, I guess), quite a lot of READMEs have badges that are using the popout or popout-square styles are using them without a logo. For example all these READMEs are using a shields badge with style=popout-square and no logo:

• https://github.com/daniu310/python/blob/a10aafe24787978ec3a676bd6d460655db424958/themes/theme-ad-master/README.md
• https://github.com/Nuglif/NGLoggerKit/blob/12dd5acbe8b78b2afd38c24b6eca379246846be4/README.md
• https://github.com/maxkrasnov/react-multilevel-select/blob/babfe26af46893113f1911893b9ab0e10c06cb42/README.md

(no special reason I've picked these - just searched GitHub to see what came up)

If we just look at requests for badges using the popout styles, we're going to overestimate the impact of removing the feature, so we want to look at requests using the popout style and also using a logo.

[RedSparr0w]

Wow, I just had a look through some too, and there is a ton of repos using the popout style without a logo.

One of the more common ones _(of what i've seen)_ is:

Edit:
If you modify the search query to this, the results mostly seem to be using it as intended.

Narrowing it down even more
roughly 985/2,148,495 repos _(number keeps reloading on refresh)_

[PyvesB]

@RedSparr0w your search returns even less results at this point, and some of them aren't actually popout badges. There may be places outside GitHub using these, but I wouldn't expect massive usage there either.

Shall we make popout and popout-square fall back to flat and flat-square respectively, and if no one complains with a good use case after a few weeks delete all related code?

[RedSparr0w]

your search returns even less results at this point

Yeah the search doesn't seem to show the most accurate numbers,
These are all taken with the same link, refreshing the page a few times:





Edit:

So I guess 1,001 is probably the "exact" total results.

---

Shall we make popout and popout-square fall back to flat and flat-square respectively, and if no one complains with a good use case after a few weeks delete all related code?

:+1: Probably the best option

[0xF6]

hey, return this feature :(

[PyvesB]

Hi @0xF6,

Sorry to hear you're unhappy about this removal. We were leaning towards getting rid of the popout style as it was not widely used and was somewhat breaking consistency, which is one of the goals of the project. However, this decision is not set in stone yet.

Could you tell us more about where you were using these badges and what additional value they brought compared to the standard logo ones?

[0xF6]

Popout badge very cute, used them to display the VSCode market and telegram badge link. (it would be possible to use a popout style on external services (azure pipelines, codacy, etc) - it would be very cool, but life is a pain)
I have long been using the service shields, but I found out about popout style quite recently, to which I was very happy.

return_popout_style! :c

[MattIPv4]

I was using popouts in every single one of my README files, as they provided some more spice to a large logo, which by default looks quite silly... It now looks quite silly...

I don't think you should be removing a format that users rely on from this service without a very long deprecation period and plenty of notice so that everyone using this style has time to make their own decision and changes...

Eg. https://github.com/MattIPv4/Avatar/blob/master/README.md

[MattIPv4]

I wonder if a better solution here would to be to make this an undocumented style so that existing users aren't affected, but new users are far less likely to make use of this style.

[chris48s]

In general, backwards compatibility and responsible deprecation is a big concern for us.

• For the NPM package, SemVer + release notes gives us an established mechanism to communicate deprecations and breaking changes.
• For self-hosting users, there is some work in flight to publish tagged releases to docker hub to try and improve this.
• For our SaaS users ( https://shields.io/ itself), we don't really have a good way to communicate changes to users. We don't know who our users are (because we're not tracking you).
  While some enthusiasts may check this repo, discord, https://twitter.com/shields_io , https://shields.io/ , etc I'd wager the vast majority of our users interact with us exclusively via images in their README (often copy-pasted from someone else's README). This means we have no back-channel to communicate changes.

The upshot of this is we try to avoid making breaking changes to the SaaS. For example, if we change a route, we'll maintain a legacy redirect for the old one. Sometimes its unavoidable. For example, if an upstream API disappears, we just have to replace the badge for that service with an error message. No more data, no more badge..

In this case, I wouldn't say we've made a _breaking_ change. The result of this is not that your badges all throw a 404 error or don't render. A fallback style has been provided - its a visual change.

A few questions for you @MattIPv4 :

• What might a good deprecation process look like for a badge, a style or a route on shields.io? (excluding package and self-hosting users)
• Where could we have posted a deprecation notice that all of our users would see it?
• If you had known "In X weeks/months, the popout style will be removed. After date Y, badges using the popout style will render as flat" (or whatever), what would you have done differently?

Cheers

[MattIPv4]

What might a good deprecation process look like for a badge, a style or a route on shields.io? (excluding package and self-hosting users)

We briefly discussed this in the Discord server and I absolutely agree that it is very hard to create a good deprecation process here. As you've stated many users (such as myself) only really interact with the service through the badges in files.

This is why I'm more of the opinion that this should've been left in the API but removed from the front-end so that legacy users still had the bad style they'd intended to use but new users wouldn't make use of the style that you don't see fit for the service any longer.

Where could we have posted a deprecation notice that all of our users would see it?

It looks like the only place this change was communicated in advance of it happening or after was this issue. Whilst I don't think there will ever be a good way to communicate such changes due to the nature of the service as above, with many users only using the images, I think to make it known on Twitter and maybe even reach out in repositories of the users who are using this style (the searches above would indicate a low number, do-able with a bot or a dedicated human) would have been good steps to help communicate this change better.

If you had known "In X weeks/months, the popout style will be removed. After date Y, badges using the popout style will render as flat" (or whatever), what would you have done differently?

For me personally, I could've made the small change to the README files at my own leisure as part of other changes. Now, all the READMEs have odd-looking badges and I need to go through every repository using my template README and update the badges to make them look nice again.

[YoshiRulz]

I used them in BizHawk's readme, but only because the icons are too damn small with flat or plastic.

[RedSparr0w]

Hmm, I'm in favor of bringing this style back,
It doesn't really add any extra overhead (other than moving templates type).
And it seems there are a few users who have noticed and are disappointed with the change. (here and on the discord)

[PyvesB]

And it seems there are a few users who have noticed and are disappointed with the change. (here and on the discord)

Indeed, however, given that this feature was available for many months and that we've got less than half a dozen complaints in total, one could argue that the impact is low. Maybe we should set up a Twitter poll or something regarding the feature's return? Users did complain about our lack of communication, I'm keen on improving that.

[MattIPv4]

we've got less than half a dozen complaints in total, one could argue that the impact is low.

Instead of justifying why we need to bring it back, rather, we should look at why exactly it was removed in the first place. To me, I don't see a need for it to have ever been removed from the service. As @RedSparr0w pointed out, "It doesn't really add any extra overhead (other than moving templates type)."

The main two justifications for removing it are 1. "I don't think they are used very often." and 2. "a complaint about them from one of the founders of shields, on the basis that consistency is a goal of the project, and offering lots of formats works against that."

I don't think either of those really justifies removing a shield type from the service. If consistency is an issue, as mentioned before, it would be fine to simply remove this type from the main site to reduce awareness, but leave it available in the actual service for those that wish to continue using this inconsistent style.

[calebcartwright]

@MattIPv4 - thanks for the feedback. There's another important aspect that @paulmelnikow mentioned in the original thread relative to the work required in #2428/#3637 to move all of the badge templates to template literals.

So IMHO, it was really about the tradeoffs for that work required for the popout template, in conjunction with the other concerns described in the OP, bandwidth of the maintainer team, etc.

If someone was willing to provide/assist with the template literal for the popout format then FWIW, I'd be a 👍 on bringing it back too.

[brandonlind]

vote for bringing back popout style. Just noticed on one of my repos. The badges looked a lot better with the popout style.

[PyvesB]

It's fair to say that we won't be bringing the popout style at this point in time, so I'm going to go ahead and close this issue.

As a summary, the reasons that have pushed us to drop this feature:

• consistency is one of the goals of the Shields project and this format worked against that.
• its usage was very low.
• it caused some maintenance overhead and additional work would have been needed in #4459/#3637. No one stepped up to assist us despite our call for help (https://github.com/badges/shields/issues/3635#issuecomment-526934603).

However, this issue did highlight that we didn't do enough on the communication side and lacked a good process for deprecating features. We've taken this feedback into account, in particular in #4564:

• we've communicated more widely about the change, using a variety of different mediums (GitHub, Discord, Twitter).
• we've asked for users' opinions through polls and discussion threads.
• we've allowed for a longer notice period (~6 weeks rather than ~2 weeks here) and have defined clearer timelines.

It's probably still not perfect, but if you have ideas to further improve things, please do let us know. We've been slowly increasing our social media presence, consider following our Twitter as it's a good way to keep track of where the project is headed!