add a note about dispatcher creating async boundary, #22436

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

@@ -287,6 +287,14 @@ which explains using and implementing GraphStages in more practical terms than t
 
 .. _Mastering GraphStages, part I: http://blog.akka.io/streams/2016/07/30/mastering-graph-stage-part-1
 
+Dispatcher attribute
+--------------------
+
+The ``ActorAttributes.dispatcher`` attribute is adding an async boundary in 2.5, since that is the typical desired behavior.
+In 2.4 an explicit `async` marker (``AsyncBoundary`` attribute) had to be added. For example, this means that ``Source`` that
+defined ``blocking-io-dispatcher`` as default followed by a ``map`` will now be separated by an async boundary, which was not
+the case in 2.4.
+
 Remote
 ======
 

akka-stream/src/main/scala/akka/stream/Attributes.scala

@@ -265,7 +265,7 @@ object ActorAttributes {
   val IODispatcher: Dispatcher = ActorAttributes.Dispatcher("akka.stream.default-blocking-io-dispatcher")
 
   /**
-   * Specifies the name of the dispatcher.
+   * Specifies the name of the dispatcher. This also adds an async boundary.
    */
   def dispatcher(dispatcher: String): Attributes = Attributes(Dispatcher(dispatcher))