Cats-effect: Create a migration guide

[djspiewak]

We need to document all the changes we've made in operational terms, so that people know what new type class to use, what functions moved around, what semantics are new can old (especially this!), etc etc. Basically everything you need to know to upgrade to 3.0.

[Daenyth]

Collecting some notes as I go:

unsafeToFuture()

import cats.effect.implicits._

def beforeF[F[_]: Effect, A](fa: F[A]): Future[A] = fa.ioIO.unsafeToFuture()
def afterF[F[_]: UnsafeRun, A](fa: F[A]): Future[A] = UnsafeRun[F].unsafeRunFutureCancelable(fa)

def beforeIO[A](ioa: IO[A]): Future[A] = ioa.unsafeToFuture()
def afterIO[A](ioa: IO[A])(implicit runtime: unsafe.IORuntime): Future[A] = ioa.unsafeToFuture()

unsafeRunSync()

import cats.effect.implicits._

def beforeF[F[_]: Effect, A](fa: F[A]): A = fa.ioIO.unsafeRunSync()
def afterF[F[_]: UnsafeRun, A](fa: F[A]): A = UnsafeRun[F].unsafeRunSync(fa)

def beforeIO[A](ioa: IO[A]): A = ioa.unsafeRunSync()
def afterIO[A](ioa: IO[A])(implicit runtime: unsafe.IORuntime): A = ioa.unsafeRunSync()

Async.fromFuture

def futureApi(): Future[Int]
def before[F[_]: Async: ContextShift]: F[Int] = Async.fromFuture(Sync[F].delay(futureApi()))
def after[F[_]: Async]: F[Int] = Async[F].fromFuture(Sync[F].delay(futureApi()))

Async.async

def intCallback(cb: Either[Throwable, Int] => Unit): Unit

def before[F[_]: Async]: F[Int] = F.async[Int](cb => intCallback(cb))

// Note: 'async_', not 'async' - the 'async_' version preserves the old signature
def after[F[_]: Async]: F[Int] = F.async_[Int](cb => intCallback(cb))

TestContext

// before; libraryDependencies on cats-effect-laws
import cats.effect.laws.util.TestContext

// after; libraryDependencies on cats-effect-testkit
import cats.effect.testkit.TestContext

[kubukoz]

just some ideas for now, I can expand them later. There's plenty left in the readme too:

ContextShift -> Async
Timer -> Temporal
Effect -> Dispatcher (UnsafeRun is gone)
Blocker -> Sync.blocking
Concurrent -> possibly Async or Sync, or even Spawn depending on usage
Bracket -> MonadCancel
shift -> cede (or nothing)
ExitCase -> Outcome/ExitCase
uncancelable -> uncancelable+poll
creating Ref/Deferred -> Ref.Make/Deferred.make
Throwable type aliases / E-parameterized typeclasses
getting a compute EC - Async

[bplommer]

Semaphore#withPermit(...) -> Semaphore#permit.use(_ => ...)

[kubukoz]

@bplommer hopefully that'll be made less cumbersome with #1338