=doc #18635 Added section about ActorSystem.shutdown being deprecated

akka-docs/rst/project/migration-guide-2.3.x-2.4.x.rst

@@ -645,4 +645,31 @@ Now:
     def deliver(destination: ActorPath)(deliveryIdToMessage: Long ⇒ Any): Unit
 
 The Java API remains unchanged and has simply gained the 2nd overload which allows ``ActorSelection`` to be
-passed in directly (without converting to ``ActorPath``).
+passed in directly (without converting to ``ActorPath``).
+
+
+Actor system shutdown
+---------------------
+``ActorSystem.shutdown``, ``ActorSystem.awaitTermination`` and ``ActorSystem.isTerminated`` has been
+deprecated in favor of ``ActorSystem.terminate`` and ``ActorSystem.whenTerminated```. Both returns a
+``Future[Terminated]`` value that will complete when the actor system has terminated.
+
+To get the same behavior as ``ActorSystem.awaitTermination`` block and wait for ``Future[Terminated]`` value
+with ``Await.result`` from the Scala standard library.
+
+To trigger a termination and wait for it to complete:
+
+    import scala.concurrent.duration._
+    Await.result(system.terminate(), 10.seconds)
+
+Be careful to not do any operations on the ``Future[Terminated]`` using the ``system.dispatcher``
+as ``ExecutionContext`` as it will be shut down with the ``ActorSystem``, instead use for example
+the Scala standard library context from ``scala.concurrent.ExecutionContext.global``.
+
+
+    // import system.dispatcher <- this would not work
+    import scala.concurrent.ExecutionContext.Implicits.global
+
+    system.terminate().foreach { _ =>
+      println("Actor system was shut down")
+    }