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

akka-actor/src/main/scala/akka/actor/ActorSystem.scala

@@ -427,12 +427,17 @@ abstract class ActorSystem extends ActorRefFactory {
    * will recursively stop all its child actors, then the system guardian
    * (below which the logging actors reside) and the execute all registered
    * termination handlers (see [[ActorSystem#registerOnTermination]]).
+   * Be careful to not schedule any operations on completion of the returned future
+   * using the `dispatcher` of this actor system as it will have been shut down before the
+   * future completes.
    */
   def terminate(): Future[Terminated]
 
   /**
    * Returns a Future which will be completed after the ActorSystem has been terminated
-   * and termination hooks have been executed.
+   * and termination hooks have been executed. Be careful to not schedule any operations
+   * on the `dispatcher` of this actor system as it will have been shut down before this
+   * future completes.
    */
   def whenTerminated: Future[Terminated]
 

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

@@ -646,3 +646,30 @@ Now:
 
 The Java API remains unchanged and has simply gained the 2nd overload which allows ``ActorSelection`` to be
 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")
+    }