search

typelevel / cats-effect

The pure asynchronous runtime for Scala
https://typelevel.org/cats-effect/
Apache License 2.0
2.03k stars 520 forks source link

Smarter version numbers in the docs #523

Open rossabaker opened 5 years ago

rossabaker commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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

hamednourhani commented 5 years ago

hi @rossabaker can is start from this task ?

alexandru commented 5 years ago

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 commented 5 years ago

@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 commented 5 years ago

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

djspiewak commented 5 years ago

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 commented 5 years ago

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 commented 3 years ago

Are we still having this problem?

keynmol commented 3 years ago

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 commented 3 years ago

Document variables sound cool.

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

djspiewak commented 3 years ago

PRs welcome on any and all of this. :-) Btw I'm willing to accept a README solution which involves badges for the "tired" and "wired" versions, just so long as they don't get confused by snapshots. I would love for this to be significantly more automated, because it really is tedious to go update the docs and go update the docusaurus main page with every release.

softinio commented 3 years ago

I'll take this issue and give it a shot to automate if ok. PR coming soon. Thanks all !

softinio commented 3 years ago

Can someone give me quick run down on how cats effect and in turn the docs are released?

Looking around, it suggests it all manual from someone laptop and not via CI being triggered due to a tag. Unless I missed something.

Thanks.

djspiewak commented 3 years ago

@softinio The hard releases are from a laptop so that the signing keys correlate (tag and artifacts). The site though is all on CI and is released continually.

Everything is from the docs branch, which has a pair of submodules: one for 2.x and one for 3.x. Those submodules refer to series/2.x and series/3.x respectively, and are updated by Dependabot roughly once a day. The dependabot updates are automatically merged when they build. The docs build runs mdoc in the submodules and integrates it with the Docusaurus versioning scheme so that everything works mostly the way you want it to (docs images from 2.x have to be put into the unversioned static directory because of Docusaurus weirdness, but that's the only foible really). Whenever the docs build runs, it publishes the compiled results directly to the gh-pages branch, which hosts the site.

So in other words, if a PR to series/3.x changes something in the docs/ folder, that change should be visible on the site within about a day after it is merged.

vasilmkd commented 3 years ago

@djspiewak Maintainers have a way to force the discovery and update if necessary, through the GitHub website.

softinio commented 3 years ago

So I have spend sometime to think about how best to solve the problem. The complexity here is the fact that release of the artifacts and the docs are completely decoupled, from what I understand.

So what I am thinking is we replace laptop releases with to a GitHub Release Tag based releases where the tag corresponds to the version the artifacts will be when published to Sonatype. Once a GitHub tag is published a new github action is run which:

Thoughts?

softinio commented 3 years ago

Also what is the release version: https://search.maven.org/artifact/org.typelevel/cats-effect_2.13/3.3-7-579f468/jar

As its not released as a snapshot but a release on Sonatype.

djspiewak commented 3 years ago

I'm pretty leery of CI releases in the context of OSS, specifically because the signing key is, in theory, the only thing that closes the trust loop between source and binary. CI releases necessitate a different key for tag signing and binary building, and only the former can be a strongly protected personal key on a physical token. However, I could be persuaded to go that route. I would need to set up a cross-signed delegate key for CI purposes, which would require doing some airgap juggling, but it's doable.

publishes the latest docs to GH Pages

Ah, here we have a bit of a problem. I think it's very important that we continue publishing the documentation continually. There are basically two possible approaches here, both of which have their own tradeoffs:

In the former scenario, changes and fixes to documentation, even minor ones, take weeks or months to show up on the site. This can be quite discouraging to contributors, since their work is invisible for a long time. The advantage though is that documentation is never "ahead" of what has been released.

In the latter scenario, documentation changes make their way to the site very quickly, but you could end up with documentation which reflects something that hasn't yet been released. In practice, this hasn't really been a concern at any point (the one time it came up was with the Tracing documentation, but we solved it by just not adding it to the site index until the release).

I pretty strongly believe that the tradeoffs of continual site delivery are superior to those of on-release site updates. Documentation is just way too precious to couple its lifecycle to something as intermittent as the full binary releases.

That unfortunately does make things harder. :-( The good news though is that the site builds with the full git state of both branches (series/2.x and series/3.x), meaning that we don't have to guess as to what the latest version is: simply looking at git tag and doing a bit of sorting and grepping should answer the question almost immediately. This means that, on every site build, we should know what the latest version is and can theoretically inject it somewhere.

There's one added bit of complexity, which is that we have to update the Scastie link on the main index.js every time we make a new release. I'm not sure if Scastie has an API where we can do this programmatically? Seems like they could add one easily enough if it doesn't already exist.

Also, as a suggestion, to lower the burden of creating release notes when a tag is created

Yeah… I think this is worth doing.

Tldr, while I'm mostly convinced on the CI releases front, I think continuous delivery on the site is a must-have, so doing away with laptop releases doesn't really get us anything. And yeah, the release drafter GHA is a lot better than it used to be, and IMO worth doing.

djspiewak commented 3 years ago

Oh, forgot to reply on the snapshot issue…

What we're doing right now is the least worst option. ☹️ The problem is that Sonatype doesn't allow versions which don't and in -SNAPSHOT to be published to the snapshots repository. This sucks because that suffix is also given magical unstable semantics, and so can't really be used for much of anything.

The hash snapshots thus have to be published to the releases repository, where they are annoying but otherwise harmless and behave the way they need to behave (as the stable versions they are). This allows the downstream ecosystem to participate in snapshot vetting and coordinated releases, which is sometimes really useful and wouldn't be possible with unstable versions, especially transitively.

Another option, proposed by @rintcius I think, would be to publish hash snapshots somewhere other than sonatype, like to github packages. That has its own associated issues (namely, you need a token to write or read artifacts), but it avoids polluting maven central at least.

vasilmkd commented 3 years ago

If I can weigh in on the issue, I would like for things to stay as they are. I don't think we've missed updating the docs right after I release (I realize the docs are slightly out of date at the moment, but it has been a really hectic release cycle with two development branches at the moment, so I don't consider it to be a problem).

I very much appreciate Daniel's release method which signs both the tag and the release with the same matching key and I very much want to keep this going forward.

As a suggestion, we could change our process to first update the docs before publishing the release. I don't think people will be flocking to download the latest version in the half hour it takes to propagate to maven central.

rintcius commented 3 years ago

Regarding the snapshot issue, Artifactory may also become an option soon https://jfrog.com/open-source/#artifactory2 which probably doesn't have the issues that github has.

mpilquist commented 3 years ago

Publishing a hash to Sonatype Snapshots with a -SNAPSHOT suffix would be better. E.g. 3.1-24-92c750d-SNAPSHOT in Sonatype Snapshots instead of 3.1-24-92c750d in Central. The only downside is that someone could overwrite the SNAPSHOT but they'd need to do so without changing the git commit hash.