Merge pull request #4230 from armanbilge/fix/soft-deprecate-future

Recommend Cats Effect `IO` as a replacement for every use case of `Future`

Author: armanbilge

core/src/main/scala-2.12/cats/instances/package.scala

@@ -39,7 +39,18 @@ package object instances {
   object deadline extends DeadlineInstances
   object function extends FunctionInstances with FunctionInstancesBinCompat0
   object partialFunction extends PartialFunctionInstances
+
+  /**
+   * @deprecated
+   *   Any non-pure use of [[scala.concurrent.Future Future]] with Cats is error prone
+   *   (particularly the semantics of [[cats.Traverse#traverse traverse]] with regard to execution order are unspecified).
+   *   We recommend using [[https://typelevel.org/cats-effect/ Cats Effect `IO`]] as a replacement for ''every'' use case of [[scala.concurrent.Future Future]].
+   *   However, at this time there are no plans to remove these instances from Cats.
+   *
+   * @see [[https://github.com/typelevel/cats/issues/4176 Changes in Future traverse behavior between 2.6 and 2.7]]
+   */
   object future extends FutureInstances
+
   object int extends IntInstances
   object invariant extends InvariantMonoidalInstances with InvariantInstances with InvariantInstancesBinCompat0
   object list extends ListInstances with ListInstancesBinCompat0

core/src/main/scala-2.13+/cats/instances/package.scala

@@ -40,7 +40,18 @@ package object instances {
   object deadline extends DeadlineInstances
   object function extends FunctionInstances with FunctionInstancesBinCompat0
   object partialFunction extends PartialFunctionInstances
+
+  /**
+   * @deprecated
+   *   Any non-pure use of [[scala.concurrent.Future Future]] with Cats is error prone
+   *   (particularly the semantics of [[cats.Traverse#traverse traverse]] with regard to execution order are unspecified).
+   *   We recommend using [[https://typelevel.org/cats-effect/ Cats Effect `IO`]] as a replacement for ''every'' use case of [[scala.concurrent.Future Future]].
+   *   However, at this time there are no plans to remove these instances from Cats.
+   *
+   * @see [[https://github.com/typelevel/cats/issues/4176 Changes in Future traverse behavior between 2.6 and 2.7]]
+   */
   object future extends FutureInstances
+
   object int extends IntInstances
   object invariant extends InvariantMonoidalInstances with InvariantInstances with InvariantInstancesBinCompat0
   object list extends ListInstances with ListInstancesBinCompat0

core/src/main/scala/cats/Invariant.scala

@@ -153,6 +153,16 @@ object Invariant extends ScalaVersionSpecificInvariantInstances with InvariantIn
 
   implicit def catsInstancesForTry: MonadThrow[Try] with CoflatMap[Try] =
     cats.instances.try_.catsStdInstancesForTry
+
+  /**
+   * @deprecated
+   *   Any non-pure use of [[scala.concurrent.Future Future]] with Cats is error prone
+   *   (particularly the semantics of [[cats.Traverse#traverse traverse]] with regard to execution order are unspecified).
+   *   We recommend using [[https://typelevel.org/cats-effect/ Cats Effect `IO`]] as a replacement for ''every'' use case of [[scala.concurrent.Future Future]].
+   *   However, at this time there are no plans to remove these instances from Cats.
+   *
+   * @see [[https://github.com/typelevel/cats/issues/4176 Changes in Future traverse behavior between 2.6 and 2.7]]
+   */
   implicit def catsInstancesForFuture(implicit
     ec: ExecutionContext
   ): MonadThrow[Future] with CoflatMap[Future] =

core/src/main/scala/cats/Semigroupal.scala

@@ -70,8 +70,19 @@ object Semigroupal extends ScalaVersionSpecificSemigroupalInstances with Semigro
   implicit def catsSemigroupalForId: Semigroupal[Id] = catsInstancesForId
   implicit def catsSemigroupalForOption: Semigroupal[Option] = cats.instances.option.catsStdInstancesForOption
   implicit def catsSemigroupalForTry: Semigroupal[Try] = cats.instances.try_.catsStdInstancesForTry
+
+  /**
+   * @deprecated
+   *   Any non-pure use of [[scala.concurrent.Future Future]] with Cats is error prone
+   *   (particularly the semantics of [[cats.Traverse#traverse traverse]] with regard to execution order are unspecified).
+   *   We recommend using [[https://typelevel.org/cats-effect/ Cats Effect `IO`]] as a replacement for ''every'' use case of [[scala.concurrent.Future Future]].
+   *   However, at this time there are no plans to remove these instances from Cats.
+   *
+   * @see [[https://github.com/typelevel/cats/issues/4176 Changes in Future traverse behavior between 2.6 and 2.7]]
+   */
   implicit def catsSemigroupalForFuture(implicit ec: ExecutionContext): Semigroupal[Future] =
     cats.instances.future.catsStdInstancesForFuture(ec)
+
   implicit def catsSemigroupalForList: Semigroupal[List] = cats.instances.list.catsStdInstancesForList
   implicit def catsSemigroupalForSeq: Semigroupal[Seq] = cats.instances.seq.catsStdInstancesForSeq
   implicit def catsSemigroupalForVector: Semigroupal[Vector] = cats.instances.vector.catsStdInstancesForVector

core/src/main/scala/cats/instances/future.scala

@@ -25,6 +25,15 @@ package instances
 import scala.concurrent.{ExecutionContext, Future}
 import scala.util.{Failure, Success}
 
+/**
+ * @deprecated
+ *   Any non-pure use of [[scala.concurrent.Future Future]] with Cats is error prone
+ *   (particularly the semantics of [[cats.Traverse#traverse traverse]] with regard to execution order are unspecified).
+ *   We recommend using [[https://typelevel.org/cats-effect/ Cats Effect `IO`]] as a replacement for ''every'' use case of [[scala.concurrent.Future Future]].
+ *   However, at this time there are no plans to remove these instances from Cats.
+ *
+ * @see [[https://github.com/typelevel/cats/issues/4176 Changes in Future traverse behavior between 2.6 and 2.7]]
+ */
 trait FutureInstances extends FutureInstances1 {
 
   implicit def catsStdInstancesForFuture(implicit

kernel/src/main/scala/cats/kernel/Semigroup.scala

@@ -288,8 +288,19 @@ private[kernel] trait MonoidInstances extends BandInstances {
     cats.kernel.instances.either.catsDataMonoidForEither[A, B]
   implicit def catsKernelMonoidForTry[A: Monoid]: Monoid[Try[A]] =
     new TryMonoid[A](Monoid[A])
+
+  /**
+   * @deprecated
+   *   Any non-pure use of [[scala.concurrent.Future Future]] with Cats is error prone
+   *   (particularly the semantics of [[cats.Traverse#traverse traverse]] with regard to execution order are unspecified).
+   *   We recommend using [[https://typelevel.org/cats-effect/ Cats Effect `IO`]] as a replacement for ''every'' use case of [[scala.concurrent.Future Future]].
+   *   However, at this time there are no plans to remove these instances from Cats.
+   *
+   * @see [[https://github.com/typelevel/cats/issues/4176 Changes in Future traverse behavior between 2.6 and 2.7]]
+   */
   implicit def catsKernelMonoidForFuture[A](implicit A: Monoid[A], ec: ExecutionContext): Monoid[Future[A]] =
     new FutureMonoid[A](A, ec)
+
   implicit def catsKernelMonoidForOption[A: Semigroup]: Monoid[Option[A]] =
     cats.kernel.instances.option.catsKernelStdMonoidForOption[A]
   implicit def catsKernelMonoidForSeq[A]: Monoid[Seq[A]] =
@@ -319,6 +330,15 @@ private[kernel] trait SemigroupInstances {
     cats.kernel.instances.either.catsDataSemigroupForEither[A, B]
   implicit def catsKernelSemigroupForTry[A: Semigroup]: Semigroup[Try[A]] =
     new TrySemigroup[A](Semigroup[A])
+
+  /**
+   * @deprecated
+   *   Any non-pure use of [[scala.concurrent.Future Future]] with Cats is error prone
+   *   (particularly the semantics of [[cats.Traverse#traverse traverse]] with regard to execution order are unspecified).
+   *   We recommend using [[https://typelevel.org/cats-effect/ Cats Effect `IO`]] as a replacement for ''every'' use case of [[scala.concurrent.Future Future]].
+   *
+   * @see [[https://github.com/typelevel/cats/issues/4176 Changes in Future traverse behavior between 2.6 and 2.7]]
+   */
   implicit def catsKernelSemigroupForFuture[A](implicit A: Semigroup[A], ec: ExecutionContext): Semigroup[Future[A]] =
     new FutureSemigroup[A](A, ec)
 }