Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Maven badge has "v" prefix #3200

Closed
1 of 3 tasks
bsideup opened this issue Mar 12, 2019 · 17 comments
Closed
1 of 3 tasks

Maven badge has "v" prefix #3200

bsideup opened this issue Mar 12, 2019 · 17 comments
Labels
question Support questions, usage questions, unconfirmed bugs, discussions, ideas

Comments

@bsideup
Copy link

bsideup commented Mar 12, 2019

Are you experiencing an issue with...

🪲 Description
The Maven metadata badges are automatically prefixed with "v" and it is misleading the users

🔗 Link to the badge

💡 Possible Solution
Remove it, or make it configurable

@paulmelnikow
Copy link
Member

Hi! Thanks for the report.

This is from https://github.com/reactor/BlockHound#getting-it and is probably what is confusing them:

Screen Shot 2019-03-12 at 7 08 33 AM

Maybe add something like "(without the 'v')" after these customized badges?

Or if you want to keep those bullet points the way they're written, use a custom XML badge:

https://img.shields.io/badge/dynamic/xml.svg?label=&color=blue&query=%2F%2Fmetadata%2Fversioning%2Fversions%2Fversion&url=https%3A%2F%2Frepo.spring.io%2Fmilestone%2Fio%2Fprojectreactor%2Ftools%2Fblockhound%2Fmaven-metadata.xml

@paulmelnikow paulmelnikow added the question Support questions, usage questions, unconfirmed bugs, discussions, ideas label Mar 12, 2019
@bsideup
Copy link
Author

bsideup commented Mar 12, 2019

Hi @paulmelnikow,

Wow, thank you, I didn't know there is such feature! I will use it for now, but would still appreciate the configurable prefix in future ☺️

bsideup added a commit to reactor/BlockHound that referenced this issue Mar 12, 2019
@paulmelnikow
Copy link
Member

I hear you. Consistency is a project goal, so would prefer to avoid adding customization options unless there’s widespread need. As far as I know, this is the first time this has been requested. There are lots of ways to hack / customize for rare use cases. I understand your perspective may be different!

@aantron
Copy link

aantron commented Sep 26, 2019

@paulmelnikow, IMO adding the v prefix harms consistency. Consider a well-run project, with well-named tags, which match package manager release versions, etc., and happen not to use vs. Using shields.io in such a project introduces these vs, which are not consistent with anything else in the project, and that confuse users and readers of the project's README.

Adding vs unconditionally enforces someone else's convention on otherwise quite clean projects. I am strongly in favor of passing version numbers through unmodified. I am not sure what the origin of adding the v prefix is, but it effectively penalizes projects that aim for consistency and do not use v, presumably in the interest of helping out projects where platform constraints or conventions make consistency impossible (but I don't know).

I would love to use more shields.io badges in my projects (and maintain them manually less), but I can't have this v. I would really appreciate either not touching versions, or making this configurable :)

@paulmelnikow
Copy link
Member

Hi @aantron, you can probably use a workaround like the dynamic badge. Which badge / project is this about?

I'm not convinced the prefix works against consistency. Few package managers use a v. Though the project in the original post (which is doing something really out of the ordinary) is an exception, across most of the projects Shields affects, the v makes the version badges clearer. It's there as a design element; it's not meant to force a v convention on anyone.

@aantron
Copy link

aantron commented Sep 26, 2019

This project, for example: https://github.com/ocsigen/lwt#readme

Or any of the other projects pinned in my profile. I'd like to display the latest GitHub tag.

across most of the projects Shields affects, the v makes the version badges clearer. It's there as a design element; it's not meant to force a v convention on anyone.

It's a convention about a design element :) And that design element creates inconsistency in projects that don't otherwise use it. If I were to use this kind of shields.io badge, I would sacrifice consistency within my projects (with changelogs, tags, commit messages), between my projects, and between my projects and the language communities I work in (their package managers' conventions, forum writing conventions, etc), for the sake of consistency across all projects that use shields.io.

I don't see why the last one should be preferable. Why shouldn't each project decide how their version numbers should be displayed? Don't the projects know best how to achieve the consistency that they need? Isn't the best way to do this by simply exposing the version numbers of the underlying system, such as GitHub or a package manager, and keeping shields.io out of the way? Why should there be a global default, affecting these strings?

I imagine there is a legitimate worry about different APIs reporting version numbers with v and without v (I'm not sure if this is true, you know best). If that's the case, I think it's most reasonable to offer v as a default, and offer the option not to rewrite, for people that don't want a rewrite.

Just prodding with questions :)

@aantron
Copy link

aantron commented Sep 26, 2019

I can see that the v may be worthwhile in badges such as npm | v1.2.3, because otherwise the badge could be ambiguous. But it's redundant in badges like release | v1.2.3, and outright harmful if otherwise (edit: that is, everywhere except this badge) the release is always named 1.2.3 :) So, again, I see the point of the use of v as a default, but the option not to do anything to the version would be nice for project authors that are carefully looking at what badges they are using, and trying to keep things clear.

@paulmelnikow
Copy link
Member

You can read a little bit about how Shields was started here: https://olivierlacan.com/posts/an-open-source-rage-diamond/ The idea behind consistency provided by Shields is to provide less choice, not more, and broadly encourage consistency across projects. We're not here to force anyone to do anything, though this goal means we have to say "no" to things.

That said…

I can see that the v may be worthwhile in badges such as npm | v1.2.3, because otherwise the badge could be ambiguous. But it's redundant in badges like release | v1.2.3, and outright harmful if otherwise (edit: that is, everywhere except this badge) the release is always named 1.2.3 :) So, again, I see the point of the use of v as a default, but the option not to do anything to the version would be nice for project authors that are carefully looking at what badges they are using, and trying to keep things clear.

That makes sense about the label. Most of the package manager badges use the name of the package manager as a label, though we have a couple, like for package.json and tag that don't.

I agree it doesn't make a lot of sense to prepend a prefix on a tag badge, where it then becomes ambiguous whether the v belongs in the tag. Since the GitHub release badges already say "release" I think the v prefix is less necessary in the design.

@aantron
Copy link

aantron commented Sep 26, 2019

Yes, agreed. The last point is especially relevant if someone (me :p) has named their badge "version," so they get... version | v1.2.3 :)

My vote is for leaving the v as the default everywhere including for GitHub tags, again for consistency of shields.io, and for a minimum of surprises in "simple" usage, but allowing the option to pass through the version unchanged, also everywhere, as a sort of alternative "simple" usage in case the v ever doesn't suit some use case. I think this is pretty easy to understand, and covers most situations quite well.

Edit: and it's backwards-compatible with the current behavior :)

@aantron
Copy link

aantron commented Sep 26, 2019

Or, another way to say it, the alternative usage would be a very welcome escape hatch of sorts.

@calebcartwright
Copy link
Member

So what's the thinking here for resolution? A new query param on the maven badge that a user could include to not add the v prefix?

I.e. something like ?includeVPrefix=false, with a default value of true?

Or is this not something we'd be able to support for the reasons articulated above?

@aantron
Copy link

aantron commented Sep 26, 2019

I suppose it would be some query param, but potentially supported on all version badges. The fact that it's available doesn't have to be documented on every version badge generator, but probably should be documented at least on the GitHub release badge generator. I don't know what's easiest here. I'm also ok with not documenting it at all :)

@paulmelnikow
Copy link
Member

paulmelnikow commented Sep 26, 2019

In the interest of providing good defaults, I'm 👍 on removing the prefix from the GitHub tag badge. To be honest, I don't think it should ever be added, because if you see tag | v9.0.0 you don't know whether the tag actually has a v in it; prepending the v to the actual tag harms clarity. Unless we get a lot of requests for it, I think we shouldn't provide an option to display a prefix on that one.

Still in two minds about the release badge; want to think a little more about that one. As a design element the v is redundant with the label, which I think is my main argument for keeping it. I want to be thoughtful about how we go about this. Another way we could go about that is a message prefix / suffix for all badges; want to think a little more about that possibility too.

It occurs to me that perhaps we should develop a bit more process around design decisions, and maybe institute some kind of RFC process to make that process more accessible!

@aantron
Copy link

aantron commented Sep 26, 2019

@paulmelnikow This sounds good :)

I want to add one more data point. For example, I would want to use the NPM version badge in one of my projects (https://github.com/aantron/repromise#readme), to keep the version number synced, but rename the label to version. In that case, the v prefix would again appear redundant, despite the underlying badge being a package manager badge. So, keeping in mind that the user can control the label, I think it's useful to be able to influence the v prefix in all badges that display a version, somehow.

In fact, the v prefix is the only reason I left the label as npm in that README, because I don't want to have, as discussed, version | v0.6.1 :)

@aantron
Copy link

aantron commented Feb 3, 2020

In light of the last couple comments, could you please reopen this issue? Alternatively, I can summarize them in a new one.

@joffrey-bion
Copy link

joffrey-bion commented Mar 12, 2021

Consistency is a project goal, so would prefer to avoid adding customization options unless there’s widespread need.

@paulmelnikow I'm all about consistency, and I would actually favor consistency within projects (between their badges, their doc and their tags) over consistency between badges of unrelated technologies. Like @aantron, this badge is the only place in my projects where the version is prefixed with a v.

To be honest, I don't think it should ever be added, because if you see tag | v9.0.0 you don't know whether the tag actually has a v in it; prepending the v to the actual tag harms clarity.

Isn't this true for all version-related badges? Some package managers have no particular constraint on the version format and the v prefix may or may not be part of it. I really believe there should have been no transformation by default on any tag/version badge. But since it's there, and to respect backwards compatibility, having an option to disable this prefix would be good enough (and very welcome :D )

@calebcartwright
Copy link
Member

calebcartwright commented Mar 12, 2021

Closing and locking this thread given the age of the thread with provided context, and refer folks to the discussion in #6135.

Please note that we consider the matter closed as well, and we're not going to remove the v nor will we be offering a query param to support doing so. The endpoint badges are incredibly easy to use, can easily be done for zero cost/zero hosting, and provide infinite customization, should anyone feel strongly enough about not having a v prefix.

@badges badges locked as resolved and limited conversation to collaborators Mar 12, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
question Support questions, usage questions, unconfirmed bugs, discussions, ideas
Projects
None yet
Development

No branches or pull requests

5 participants