Smarter version numbers in the docs

[rossabaker]

When we release, we have to change the version number twice in the README and once in the tut. The README is currently included directly in the site. sbt-microsite has some automation for the latter, but can't help with the former.

1. Consider making a more anemic README that drives straight to the site.
2. Derive the version number in the site when publishing.

Failure to do so was responsible for #252.

Relevant Gitter conversation

[kamilkloch]

As for the version number, I continue to see v1.2.0 in the badge on the top of the README.md, despite https://index.scala-lang.org/typelevel/cats-effect/cats-effect/latest.svg?color=orange correctly pointing to v1.3.0. Github image caching issues?

[djspiewak]

Yeah those badges take a bit to update due to caching.

[hamednourhani]

hi @rossabaker can is start from this task ?

[alexandru]

The badges are problematic as Scala index is also unfamiliar with our practice of publishing hash versions from time to time, for testing purposes and the badges ends up displaying those.

[alexandru]

@rossabaker

Consider making a more anemic README that drives straight to the site.

Many people land on the GitHub repository and I prefer having an easy copy-paste-able version number. It's a personal preference, but it annoys me when projects don't do this and I end up searching on search.maven.org which isn't cool.

Derive the version number in the site when publishing.

Note that the website often gets published out of sync with the actual versions being published on Sonatype.

When publishing on Sonatype, SBT is configured to take the version number from the current tag, but that's not going to cut it for the website.

[alexandru]

Btw, automation would be cool, but having a checklist for maintainers might be OK too 🙂

[djspiewak]

Many people land on the GitHub repository and I prefer having an easy copy-paste-able version number. It's a personal preference, but it annoys me when projects don't do this and I end up searching on search.maven.org which isn't cool.

This. Forever this.

[rossabaker]

Ha! I almost always go to search.maven.org, because the manually kept readme is usually a lie. Or I at minimum check the tags after I copy and paste.

I'm willing to try a maintainer checklist since I'm apparently the outlier.

[softinio]

Are we still having this problem?

[keynmol]

I believe @djspiewak is still manually updating version numbers in README like a crazy person.

Overall I very much agree with Ross that README is almost always a lie (unless someone updates it manually for every release, see crazy above).

This can be made a

a) touch smarter by using mdoc's document variables
b) lot smarter by just having custom code for docs module like metals does it (although metals is even more complicated, because of snapshots)

The README can point to just the two CE versions' websites where the first page is installation with most up-to-date version being front and centre.

[alexandru]

Document variables sound cool.

Another possibility, to keep the README in sync is to introduce a script that fails the build on version tags.