search

scalacenter / scaladex

The Scala Package Index
https://index.scala-lang.org
BSD 3-Clause "New" or "Revised" License
197 stars 76 forks source link

Implement the Shields specification for badges #315

Open adamvoss opened 7 years ago

adamvoss commented 7 years ago

I think the badges being provided by Scaladex are a great idea. However, they have the characteristic of not being especially clear as to what they mean. The shields.io project has a specification that seems fairly well respected and remedies this problem. I propose the scaladex badges be modified to implement the Shields spec.

The badges currently in README.md: Count Badge

Latest version

Count Badge

Latest version

Would become:

Unfortunately, this will affect anywhere existing that uses the badge. If anywhere is using badges for different projects on the same there use case will likely be broken because it is not supported by the spec.

I will miss seeing the badge telling me there are 68 cats though :heart:

heathermiller commented 7 years ago

Couldn't we just add more information to these badges though? E.g.,:

Count Badge

heathermiller commented 7 years ago

I get your point that in akka's README, it's probably already obvious that we're looking at akka. But I guess customizable badges are interesting for people to post on their homepages or resumes maybe? Just brainstorming here.

adamvoss commented 7 years ago

I think that the conventional and standard use cases are the best ones to optimize (in this case READMEs). Consistency helps users cultivate feelings of familiarity and reduces the mental load of end-users.

If wanting to explicitly support the sample badge you gave, I would think that the best way to do so would be to represented the information in a 3-section badge. I have only recall seeing one of those once and I cannot locate one at the moment. (Edit: found a source of a 3-section badge: https://buildstats.info/)

Rather than providing arbitrary badging support, I think it would be better to provide suitable web services for getting information from Scaladex. From those users wanting to do something custom with badges would have complete control of badge design and users could utilize the information in forms other than badges, opening up even more possibilities..

Looking at the implementation, it appears there are two types of badges.

The meaning of a version badge is well known to Scaladex so it could define both sides of the badge and be made consistent with the Shields specification and typical convention without likely having much of an impact.

However, count badges appear to display the count of arbitrary queries. In order for Scaladex to be able to provide a meaningful left-hand side, it would need to be able to translate the query to more human readable meaning. Keeping the left-hand side user-defined is probably the path of least resistance for count badges.

If a particular type of query, such as "dependents", is noticed as popular or particularly useful for count badges, then it may make sense to make it a new badge type which would provide consistency across usages and make it easier for consumers to create the badge. Thus, following the Shields spec would be up to consumers; however, Scaladex's examples could be updated to be consistent.

I would also encourage the spec be considered when future badges are added.