Provide a 'Create Badge' function for users #670

rtyley · 2021-05-28T16:32:39Z

This work follows on from #660 - the markdown required to display a badge is fairly verbose:

[![algebra-laws Scala version support](https://index.scala-lang.org/typelevel/algebra/algebra-laws/latest-by-scala-version.svg)](https://index.scala-lang.org/typelevel/algebra/algebra-laws)

...it's nice to be able to help people to create it:

video.mp4

Travis CI, GitHub and others follow this pattern of showing both the badge, and the recommended markdown to display it.

cc @adpi2

I contributed slightly broken versions of these in scalacenter#660

The markdown required to create a badge is fairly verbose: ``` [![algebra-laws Scala version support](https://index.scala-lang.org/typelevel/algebra/algebra-laws/latest-by-scala-version.svg)](https://index.scala-lang.org/typelevel/algebra/algebra-laws) ``` ...it's nice to be able to help people to create it. Travis CI, GitHub and others follow this pattern to show both the badge, and the recommended markdown to display it.

rtyley · 2021-05-28T16:34:47Z

server/src/main/assets/css/partials/_main.scss

+            visibility: hidden;
+            opacity: 0;
+        }
+        .overlay:target {


This is using the 'Pure-CSS lightbox' technique to create a modal overlay without any javascript:

https://developer.mozilla.org/en-US/docs/Web/CSS/:target#pure-css_lightbox

Really nice too!

rtyley · 2021-05-28T16:36:49Z

server/src/main/assets/css/partials/_main.scss

@@ -14,6 +14,10 @@ main {
    flex: 1;
 }

+.copyable-incantation {
+  user-select: all;


This has the nice effect of the user selecting the entire text sample, rather just a word, when they click on it - at that point it's very easy to copy & paste the entire expression, so it's a nice complement (or possibly even replacement) to the Javascript 'Copy' button.

Nice trick!

adpi2 · 2021-05-31T08:57:48Z

Thanks for this contribution, that's a really nice idea!

I have deployed this PR on the dev server for testing: https://index-dev.scala-lang.org/

A few remarks about the end result:

I think the badge should be placed in the right side bar in its own box, before the sbt/Maven installation box. That's because the badge can be quite verbose, also we may want to add the Scala.js and Scala Native badges too.
It doesn't work when the main artifact is an sbt plugin: see for example sbt-assembly

Suggested in scalacenter#670 (comment) ...not entirely sure if it's better there, especially as the available space is even more narrow.

So if we're looking at: https://index.scala-lang.org/typelevel/cats/cats-core/2.6.1?target=_sjs1.x_3.x ...we want to see the badge with `targetType=js`, rather than the default badge that displays JVM-based artifacts.

Suggested in scalacenter#670 (comment) ...not entirely sure if it's better there, especially as the available space is even more narrow.

rtyley · 2021-06-02T22:34:41Z

Hi @adpi2 , thanks for you feedback!

Handling non-JVM artifacts (Scala.JS, sbt, etc)

It doesn't work when the main artifact is an sbt plugin: see for example sbt-assembly

I've pushed commit 3e7498e, which hopefully goes some way to addressing this. The badge now uses the targetType that matches the selected target for the page - so if the user has selected https://index-dev.scala-lang.org/typelevel/cats/cats-core/2.6.1?target=_sjs1.x_3.x , the badge will be showing Scala.JS compatability, rather than the default JVM-based badge.

For sbt in particular, the badge displayed looks like this:

..this isn't really ideal - for sbt, where sbt version fully determines the Scala version used, it would be better for the badge to simply display sbt versions, rather than Scala versions, like this:

...that's probably a fix for a separate PR tho'. (edit: done in #674)

Badge placement

I think the badge should be placed in the right side bar in its own box, before the sbt/Maven installation box. That's because the badge can be quite verbose, also we may want to add the Scala.js and Scala Native badges too.

The good news is that it might not be necessary to display multiple badges at once, if the "badge-targetType-matches-the-selected-target" tweak above is acceptable.

I wasn't sure if moving the badge to the RHS bar was better - the space is even more narrow, so most of the badge gets lost, and I couldn't find any clean CSS techniques to fade out the right -hand side of the badge to indicate it was truncated. As I wasn't certain about it, I've put that change into a badge-display-in-own-box-on-RHS-bar branch for now, and you can see the screenshots of the two options below:

Badge placed in the Project Info

This does have the advantage of being a wide part of the layout, so we get to see a fair amount of the badge:

Badge placed in it's own box on the RHS bar

This is unfortunately quite a narrow space - we don't get to see much of the badge:

adpi2 · 2021-06-07T12:47:09Z

New changes deployed: https://index-dev.scala-lang.org/

Handling non-JVM artifacts (Scala.JS, sbt, etc)

Looks good to me.

..this isn't really ideal - for sbt, where sbt version fully determines the Scala version used, it would be better for the badge to simply display sbt versions, rather than Scala versions

I agree. It can be done in another PR.

Badge placement

I still think it should be placed on the RHS because:

the library author is likely to put it in the readme as well
it is kind of redundant with the versions drop down (when you choose a Scala version, it refreshes with the latest version)

According to me, this 'Create Badge' section is useful to copy-paste the markdown piece but it should not be placed in the project header, because it would add too much redundancy.

I wasn't sure if moving the badge to the RHS bar was better - the space is even more narrow, so most of the badge gets lost, and I couldn't find any clean CSS techniques to fade out the right -hand side of the badge to indicate it was truncated

Have you tried overflow: scroll as in the Installation section?

Suggested in scalacenter#670 (comment) Advantages ---------- * If the project already has the badge in it's project README, then it would be repetitious to show the badge immediately above it in the project header. * If we consider the visible badge on the project page as just a link to the markdown-generator lightbox, rather than informational in itself (given that version information is already visible in the versions dropdown), then there is no need to prominently display the full badge. Disadvantages ------------- * Narrower space usually truncates the (very wide) badge. Mitigating against this is the argument that the badge here is just a link, rather than informational. * Takes up more space vertically, so the consumed screen-area is somewhat larger than with the badge in the project header, even though it's narrower! It would be nice if there was a visual indication that the badge was truncated on the right. Using `overflow: scroll` gives an always-present scrollbar, which I find visually cluttered and more than what's needed- we don't really want to scroll the badge from side-to-side, when we can just click on it to view the whole thing.

adpi2 · 2021-06-11T09:18:44Z

Thanks again @rtyley for your contribution! It's deployed in production: https://index.scala-lang.org/

I agree the current placement is not ideal. We, at the Scala Center team, are currenlty thinking of redesigning the project page in different tabs: project tab, and releases tab. With this redesign the version dropdowns will probably go to the release tab, and then we will be able to find a better place for the badge.

rtyley · 2021-06-11T11:24:04Z

Thanks @adpi2 ! That's cool - I'm on holiday at the moment so wasn't able to respond properly to your feedback, but many thanks for releasing!

Each release of sbt uses a specific version of Scala (1.0 uses Scala 2.12, 0.13 uses Scala 2.10), so the sbt version of a plugin fully determines the Scala language binary version it uses - this means, for a user, it's only really interesting to know the sbt version of the plugin, not the Scala language version. At the moment, the Scaladex badge for, eg, the `sbt-assembly` plugin reads `1.0.0 (Scala 2.12, 2.10)` - for the user, it would be more helpful if it read `1.0.0 (sbt 1.0, 0.13)` - listing the versions of sbt you can actually use it with! Although the Scaladex badge did have some logic to display platform versions supported by _all_ listed Scala language versions, that didn't help in this situation, as the Scala language version differs for each platform version of sbt. This commit updates the Scaladex badge logic to have two version-summary strategies: * `SummariseLanguageVersion` - which was the existing strategy, listing notable Scala version support, secondarily adding in a summary of platform editions (eg 'JS 1.0+0.6, Native 0.4') scalacenter#670 (comment)

Each release of sbt uses a specific version of Scala (1.0 uses Scala 2.12, 0.13 uses Scala 2.10), so the sbt version of a plugin fully determines the Scala language binary version it uses - this means, for a user, it's only really interesting to know the sbt version of the plugin, not the Scala language version. At the moment, the Scaladex badge for, eg, the `sbt-assembly` plugin reads `1.0.0 (Scala 2.12, 2.10)` - for the user, it would be more helpful if it read `1.0.0 (sbt 1.0, 0.13)` - listing the versions of sbt you can actually use it with! Although the Scaladex badge did have some logic to display platform versions supported by _all_ listed Scala language versions, that didn't help in this situation, as the Scala language version differs for each platform version of sbt. This commit updates the Scaladex badge logic to have two version-summary strategies: * `SummariseLanguageVersion` - which was the existing strategy, listing notable Scala version support, secondarily adding in a summary of platform editions (eg 'Scala 2.13 - Native 0.4+0.3') * `SummarisePlatformEdition` - the new strategy, which is used if *all* fetched `ScalaTarget`s for an artifact have a `targetType` for which the platform version fully determines the Scala version (as is the case for sbt). It omits the Scala version from the summary, and just relates the platform versions (eg `sbt 1.0, 0.13`) scalacenter#670 (comment)

Each release of sbt uses a specific version of Scala (1.0 uses Scala 2.12, 0.13 uses Scala 2.10), so the sbt version of a plugin fully determines the Scala language binary version it uses - this means, for a user, it's only really interesting to know the sbt version of the plugin, not the Scala language version. At the moment, the Scaladex badge for, eg, the `sbt-assembly` plugin reads `1.0.0 (Scala 2.12, 2.10)` - for the user, it would be more helpful if it read `1.0.0 (sbt 1.0, 0.13)` - listing the versions of sbt you can actually use it with! Although the Scaladex badge did have some logic to display the platform versions supported by _all_ listed Scala language versions, that doesn't help in this situation, as the Scala language version differs for each platform version of sbt. This commit updates the Scaladex badge logic to have two version-summary strategies: * `SummariseLanguageVersion` - which was the existing strategy, listing notable Scala version support, secondarily adding in a summary of platform editions (eg 'Scala 2.13 - Native 0.4+0.3') * `SummarisePlatformEdition` - the new strategy, which is used if *all* fetched `ScalaTarget`s for an artifact have a `targetType` for which the platform version fully determines the Scala version (as is the case for sbt). It omits the Scala version from the summary, and just relates the platform versions (eg `sbt 1.0, 0.13`) scalacenter#670 (comment)

Each release of sbt uses a specific version of Scala (1.0 uses Scala 2.12, 0.13 uses Scala 2.10), so the sbt version of a plugin fully determines the Scala language binary version it uses - this means, for a user, it's only really interesting to know the sbt version of the plugin, not the Scala language version. At the moment, the Scaladex badge for, eg, the `sbt-assembly` plugin reads `1.0.0 (Scala 2.12, 2.10)` - for the user, it would be more helpful if it read `1.0.0 (sbt 1.0, 0.13)` - listing the versions of sbt you can actually use it with! Although the Scaladex badge did have some logic to display the platform versions supported by _all_ listed Scala language versions, that doesn't help in this situation, as the Scala language version differs for each platform version of sbt. See also this comment from a prior PR: scalacenter#670 (comment) This commit updates the Scaladex badge logic to have two version-summary strategies: * `SummariseLanguageVersion` - which was the existing strategy, listing notable Scala version support, secondarily adding in a summary of platform editions (eg 'Scala 2.13 - Native 0.4+0.3') * `SummarisePlatformEdition` - the new strategy, which is used if *all* fetched `ScalaTarget`s for an artifact have a `targetType` for which the platform version fully determines the Scala version (as is the case for sbt). It omits the Scala version from the summary, and just relates the platform versions (eg `sbt 1.0, 0.13`)

The 'Create Badge' function was introduced with scalacenter#670, but unfortunately a small typo was introduced with scalacenter#705, removing the closing bracket on the markdown the user will copy - so instead of this: [![play-v28 Scala version support](https://index.scala-lang.org/guardian/play-secret-rotation/play-v28/latest-by-scala-version.svg](https://index.scala-lang.org/guardian/play-secret-rotation/play-v28) ...there's this broken markdown: [![play-v28 Scala version support](https://index.scala-lang.org/guardian/play-secret-rotation/play-v28/latest-by-scala-version.svg](https://index.scala-lang.org/guardian/play-secret-rotation/play-v28

The 'Create Badge' function was introduced with scalacenter#670, but unfortunately a small typo was introduced with scalacenter#705, removing two closing brackets on the markdown the user will copy - so instead of this: [![play-v28 Scala version support](https://index.scala-lang.org/guardian/play-secret-rotation/play-v28/latest-by-scala-version.svg)](https://index.scala-lang.org/guardian/play-secret-rotation/play-v28) ...there's this broken markdown: [![play-v28 Scala version support](https://index.scala-lang.org/guardian/play-secret-rotation/play-v28/latest-by-scala-version.svg](https://index.scala-lang.org/guardian/play-secret-rotation/play-v28

rtyley added 3 commits May 28, 2021 17:24

Fix markdown for Badge links in README

be4091f

I contributed slightly broken versions of these in scalacenter#660

Fix broken links to Scala tools in dependency incantations

b325776

rtyley commented May 28, 2021

View reviewed changes

rtyley added a commit to rtyley/scaladex that referenced this pull request Jun 2, 2021

Move badge display to it's own box on RHS bar

1c8ba45

Suggested in scalacenter#670 (comment) ...not entirely sure if it's better there, especially as the available space is even more narrow.

Display badge for targetType appropriate to release

3e7498e

So if we're looking at: https://index.scala-lang.org/typelevel/cats/cats-core/2.6.1?target=_sjs1.x_3.x ...we want to see the badge with `targetType=js`, rather than the default badge that displays JVM-based artifacts.

rtyley force-pushed the help-users-create-badge-markdown branch from 1656f4d to 3e7498e Compare June 2, 2021 21:46

rtyley added a commit to rtyley/scaladex that referenced this pull request Jun 2, 2021

Move badge display to it's own box on RHS bar

9182175

Suggested in scalacenter#670 (comment) ...not entirely sure if it's better there, especially as the available space is even more narrow.

adpi2 approved these changes Jun 11, 2021

View reviewed changes

adpi2 merged commit 302314d into scalacenter:main Jun 11, 2021

rtyley mentioned this pull request Jul 4, 2021

Better support for sbt artifacts in the Scaladex badge #674

Merged

rtyley mentioned this pull request Dec 24, 2021

Fix 'Create Badge' markdown closing-bracket typos #786

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Provide a 'Create Badge' function for users #670

Provide a 'Create Badge' function for users #670

rtyley commented May 28, 2021 •

edited

Loading

rtyley May 28, 2021

adpi2 May 31, 2021

rtyley May 28, 2021 •

edited

Loading

adpi2 May 31, 2021

adpi2 commented May 31, 2021 •

edited

Loading

rtyley commented Jun 2, 2021 •

edited

Loading

adpi2 commented Jun 7, 2021

adpi2 commented Jun 11, 2021

rtyley commented Jun 11, 2021

Provide a 'Create Badge' function for users #670

Provide a 'Create Badge' function for users #670

Conversation

rtyley commented May 28, 2021 • edited Loading

rtyley May 28, 2021

Choose a reason for hiding this comment

adpi2 May 31, 2021

Choose a reason for hiding this comment

rtyley May 28, 2021 • edited Loading

Choose a reason for hiding this comment

adpi2 May 31, 2021

Choose a reason for hiding this comment

adpi2 commented May 31, 2021 • edited Loading

rtyley commented Jun 2, 2021 • edited Loading

Handling non-JVM artifacts (Scala.JS, sbt, etc)

Badge placement

Badge placed in the Project Info

Badge placed in it's own box on the RHS bar

adpi2 commented Jun 7, 2021

Handling non-JVM artifacts (Scala.JS, sbt, etc)

Badge placement

adpi2 commented Jun 11, 2021

rtyley commented Jun 11, 2021

rtyley commented May 28, 2021 •

edited

Loading

rtyley May 28, 2021 •

edited

Loading

adpi2 commented May 31, 2021 •

edited

Loading

rtyley commented Jun 2, 2021 •

edited

Loading