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()
// Note: Using a `Dispatcher` resource is cheap - don't worry about it
def preferredAfterF[F[_]: Async, A](fa: F[A]): F[Future[A]] = Dispatcher[F].use(_.unsafeToFuture(fa))

// Note: It's not certain whether dispatcher passed implicitly will be the canonical style, or whether it will be explicit argument instead
def ifNeededAfterF[F[_], A](fa: F[A])(implicit D: Dispatcher[F]): Future[A] = d.unsafeToFuture(fa)


def beforeIO[A](ioa: IO[A]): Future[A] = ioa.unsafeToFuture()
def afterIO[A](ioa: IO[A]): IO[Future[A]] = Dispatcher[IO].use(_.unsafeToFuture(ioa))
def ifNeededAfterIO(ioa: IO[A])(implicit D: Dispatcher[IO]): Future[A] = D.unsafeToFuture(ioa)

unsafeRunSync()

import cats.effect.implicits._

def beforeF[F[_]: Effect, A](fa: F[A]): A = fa.ioIO.unsafeRunSync()
// Avoid this pattern; instead wrap both the `unsafeRunSync` call *and* the thing that needs it, so that it can be contained within the scope of a `Dispatcher[F].use(...)` block.
def ifNeededAfter[F[_], A)(fa: F[A])(implicit D: Dispatcher[F]): A = D.unsafeRunSync(fa)

def beforeIO[A](ioa: IO[A]): A = ioa.unsafeRunSync()
def afterIO[A](ioa: IO[A]): 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

[kubukoz]

If nobody beats me to it, I'll take this one of these days and make something structured.

Note to self: start with the new artifacts.

[kubukoz]

I have... a branch! And a heading!

[djspiewak]

The heading and first sentence are always the hardest part

[kubukoz]

Progress so far: #1687