diff --git a/CHANGELOG-2.1.md b/CHANGELOG-2.1.md
index cf9c8c20a7..848bb20174 100644
--- a/CHANGELOG-2.1.md
+++ b/CHANGELOG-2.1.md
@@ -304,6 +304,9 @@ To get the diff between two versions, go to https://github.com/symfony/symfony/c
    attributes storage behaviour from 2.0.x (default).
  * Added `Symfony\Component\HttpFoundation\Attribute\NamespacedAttributeBag` for
    namespace session attributes.
+ * Flash API can stores messages in an array so there may be multiple messages
+   per flash type.  The old `Session` class API remains without BC break as it
+   will single messages as before.
 
 ### HttpKernel
 
diff --git a/UPGRADE-2.1.md b/UPGRADE-2.1.md
index 2a4927a5ec..556ff78ac6 100644
--- a/UPGRADE-2.1.md
+++ b/UPGRADE-2.1.md
@@ -306,16 +306,6 @@ UPGRADE FROM 2.0 to 2.1
 
     Before:
 
-    ```
-    {% if app.session.hasFlash('notice') %}
-        <div class="flash-notice">
-            {{ app.session.flash('notice') }}
-        </div>
-    {% endif %}
-    ```
-
-    After:
-
     ```
     {% if app.session.flashbag.has('notice') %}
         <div class="flash-notice">
@@ -323,14 +313,25 @@ UPGRADE FROM 2.0 to 2.1
         </div>
     {% endif %}
     ```
+    After:
+
+    ```
+    {% for flashMessage in app.session.flashbag.get('notice') %}
+        <div class="flash-notice">
+            {{ flashMessage }}
+        </div>
+    {% endfor %}
+    ```
 
     You can process all flash messges in a single loop with:
 
     ```
-    {% for type, flashMessage in app.session.flashbag.all() %}
-        <div class="flash-{{ type }}">
-            {{ flashMessage }}
-        </div>
+    {% for type, flashMessages in app.session.flashbag.all() %}
+        {% for flashMessage in flashMessages) %}
+            <div class="flash-{{ type }}">
+                {{ flashMessage }}
+            </div>
+        {% endfor %}
     {% endfor %}
     ```