C#: Add change note

change-notes/1.25/analysis-csharp.md

@@ -28,7 +28,8 @@ The following changes in version 1.25 affect C# analysis in all applications.
   such as `A<int>.B`, no longer are considered unbound generics. (Such nested types do,
   however, still have relevant `.getSourceDeclaration()`s, for example `A<>.B`.)
 * The data-flow library has been improved, which affects most security queries by potentially
-  adding more results. Flow through methods now takes nested field reads/writes into account.
+  adding more results:
+  - Flow through methods now takes nested field reads/writes into account.
     For example, the library is able to track flow from `"taint"` to `Sink()` via the method
     `GetF2F1()` in
     ```csharp
@@ -50,5 +51,28 @@ The following changes in version 1.25 affect C# analysis in all applications.
         }
     }
     ```
+  - Flow through collections is now modeled precisely. For example, instead of modeling an array
+    store `a[i] = x` as a taint-step from `x` to `a`, we now model it as a data-flow step that
+    stores `x` into `a`. To get the value back out, a matching read step must be taken.
+
+    For source-code based data-flow analysis, the following constructs are modeled as stores into
+    collections:
+    - Direct array assignments, `a[i] = x`.
+    - Array initializers, `new [] { x }`.
+    - C# 6-style array initializers, `new C() { Array = { [i] = x } }`.
+    - Call arguments that match a `params` parameter, where the C# compiler creates an array under-the-hood.
+    - `yield return` statements.
+
+    The following source-code constructs read from a collection:
+    - Direct array reads, `a[i]`.
+    - `foreach` statements.
+
+    For calls out to library code, existing flow summaries have been refined to precisely
+    capture how they interact with collection contents. For example, a call to
+    `System.Collections.Generic.List<T>.Add(T)` stores the value of the argument into the
+    qualifier, and a call to `System.Collections.Generic.List<T>.get_Item(int)` (that is, an
+    indexer call) reads contents out of the qualifier. Moreover, the effect of
+    collection-clearing methods such as `System.Collections.Generic.List<T>.Clear()` is now
+    also modeled.
 
 ## Changes to autobuilder