PyPI version badge doesn't include a link

[abitrolly]

Are you experiencing an issue with...

shields.io

🐞 Description

Generated markup for PyPI version badge doesn't include a link to package repo.

![PyPI](https://img.shields.io/pypi/v/hy)

Expected this code.

[![PyPI Version](https://img.shields.io/pypi/v/hy.svg)](https://pypi.python.org/pypi/hy)

https://github.com/badges/shields/blob/master/doc/TUTORIAL.md doesn't make it immediately obvious how to pass target param from example template to markdown. Maybe add some mermaid diagrams to it?

🔗 Link to the badge

/pypi/v

💡 Possible Solution

No response

[chris48s]

The markdown we generate doesn't usually wrap the image in a link for any service (its not just pypi - its the same for all badges).

doesn't make it immediately obvious how to pass target param from example template to markdown

At the moment we only use this when the badge is a result from the "suggest badges" feature - in that case, the generated markdown (or rst or whatever) will link to the project URL from the 'suggest' search. I always forget this exists until I dig in to the frontend code.

[abitrolly]

The markdown we generate doesn't usually wrap the image in a link for any service.

Why not?

Where to see the "suggested badges"? It is not present on the front page.

[chris48s]

So there's 2 questions here..

Why not?

You're not the first person to suggest this as a feature. This is a dupe of other issues like #7438 , #4726 (and others) but although someone occasionally pops up with a query, nobody has really wanted to push it forward.

In principle it would be possible to add a property or method on each badge class that allows us to generate a link based on the badge params to wrap the image (obviously the url we assemble to make an API call for data is a different thing from the URL you might want a user to visit). We've never done it. I don't think I've ever really articulated my thoughts on it, but..

There are some reasons why would be a reasonable thing to do, if someone really wanted to champion it:

• Users often choose to wrap these things with a link "in the wild" (although predictably, not everyone makes the exact same choice)
• GitHub's default behaviour (which is our primary source of traffic) is to make all images a link to the (proxied) image itself so you can't have a badge in a GH readme which is just not a link to anything.

There would be a number of considerations for us of maintainers of varying levels of importance:

• Its another detail to debate in every PR
• There is probably some murky 'promotional vs informational' ground to resolve here
• For some services there isn't a natural thing to link to, or there are several possible options. In general we try not to be too 'editorial' about these things
• For some services there may not be a natural thing to link to for all variants of the badge
• We've got some-hundred existing services to think about (not necessarily a problem - gotta start somewhere)
• In a minority of cases it might not be possible to generate the most sensible human-facing link from only the params necessary to make an API call to get the data for the badge

In the grand scheme of things, I'm on the fence.

Where to see the "suggested badges"?

If you paste a URL into the search box (instead of just a search term) on https://shields.io/ a button will appear that says "suggest badges". The suggestions may or may not be helpful. It is a bit of a strange legacy "feature" that probably needs to be retired but that feature is the reason why the frontend code has the ability to generate markdown/rst/etc with a link.

[abitrolly]

It is not quite obvious that frontend generates badge configuration form from service.js examples. There can be just one example, right? So the service.js is used both for generating the badge and for generating form for the badge.

graph LR;
G[get badge] --> backend --> S[service.js:handle]
GB[generate badge] --> frontend --> SE[service.js:examples]

Loading

So this is the code that is used for configuration.

shields/services/pypi/pypi-version.service.js

Lines 10 to 18 in af47032

	static examples = [
	{
	title: 'PyPI',
	pattern: ':packageName',
	namedParams: { packageName: 'nine' },
	staticPreview: this.render({ version: '1.0.0' }),
	keywords: ['python'],
	},
	]

It is not completely clear if a separate URL field should be added directly to mapping, or to pattern/namedParams. Also not clear how to make packageName substitution in this static form.

The suggestions may or may not be helpful.

Not helpful for https://pypi.org/project/hy/ indeed. The code for button generation IMHO deserves to be in a separate class. It could expose prefixes for suggestions and methods for compiling necessary fields for markup. Not every badge needs a link, so it could be optional.

The frontend code that generates markup.

shields/frontend/components/customizer/customizer.tsx

Lines 76 to 81 in af47032

	const markup = generateMarkup({
	badgeUrl: builtBadgeUrl,
	link,
	title,
	markupFormat,
	})

How to pass badge info there? And where frontend actually accesses service examples?

[calebcartwright]

@abitrolly -

Chris articulated quite clearly why this feature does not exist today, as well the things that would need to be discussed to determine if this is even a feature we should pursue.

It's not clear to me from your comments whether you are simply suggesting a feature/asking a question about the absence of the feature, or if this is now a feature you would like to work on.

It would be helpful if you could clarify that.

Additionally, even if this is something you'd like to work on, there's still some conversation that needs to happen first to determine whether this is a feature we want to incorporate (taking into account the plans to overhaul the website) before we start diving into any specific implementation details or class/function level structure.

[abitrolly]

I'd like to work on adding URL to generated markup. Although my knowledge if React/TypeScript and Gatsby ecosystem is close to zero.

Is there an issue with plans about overhauling the website? Quite curious what is wrong with current approach that it is needed.

[chris48s]

I think before anyone starts on an implementation for this one, the key question is: would we as the core team want to take on this feature? The long tail of maintenance would affect every existing badge (4 or 5 hundred, depending on how you count the variants) and every future PR adding a new badge.

Do you have any further thoughts beyond the points I've already listed Caleb?

[abitrolly]

@chris48s but the URL is not obligatory for each badge. Or do you foresee a lot of people adding URLs to badges?

[chris48s]

If we added this, it would be a feature that could be used for any badge. If we're going to say we use it in some cases but not others, we'd need to clearly state and document when we use it and when we don't.

The PyPI version badge is not special in the context of the hundreds of badges we have. We wouldn't add this just for PyPI Version and nothing else.

[calebcartwright]

Do you have any further thoughts beyond the points I've already listed Caleb?

Bah sorry, I forgot to hit the comment button the other day. To the question asked, my answer is no. I think you've perfectly laid out the considerations and an approach we can take for moving forward.

At the highest level I'll say that I'm ambivalent around the overarching question of whether we should do this. I think it's fair to say that we've a dearth of frontend resources and expertise, and increasingly limited maintainer bandwidth overall, so I'm generally hesitant to expand the frontend footprint feature wise. However, I acknowledge it's not too far a stretch (at least as far as an end user experience capability perspective goes) so I could be convinced this is worthwhile.

At a minimum, I feel like the existing feature should be made more prominent as part of the UX redesign (#7815) because it is currently essentially an easter egg. It's one of those "if ya know ya know" deals, but is otherwise completely missed.

Is there an issue with plans about overhauling the website? Quite curious what is wrong with current approach that it is needed.

@abitrolly - there's been a desire to modernize and evolve the frontend shields.io website for a while, and #7815 (and the issues linked within) contain relevant discussions and considerations. It's fantastic that you're interested in working on markdown enhancement features, it's just that like Chris said, the Shields team needs to first figure out if this is something we should do, and then if so, how this should be surfaced/presented to end users, all prior to deep dive implementation discussions. You're more than welcome to participate in this dialogs too, we just wanted to stress that we're no where near a point where we can start talking about code/class level details

[calebcartwright]

Oh and I guess another point I'll add is that there are some badges which do arguably have a natural link that could be included, but I've found I actually dislike that link and use another 99% of the time. In such cases I'd be annoyed if I had to cut out part of the generated markdown Shields gave me