Added migration section

Author: dvd101x

docs/datatypes/matrices.md

@@ -270,12 +270,12 @@ in the matrix, and if not, a subset of the matrix will be returned.
 
 A subset can be defined using an `Index`. An `Index` contains a single value
 or a set of values for each dimension of a matrix. An `Index` can be
-created using the function `index`. When getting a single value from a matrix,
-`subset` will return the value itself instead of a matrix containing just this 
-value.
+created using the function `index`. The way `subset` returns results depends on how you specify indices for each dimension:
 
-**New behavior:**  
-When using `subset`, indexing a dimension with a scalar removes that dimension from the result, while indexing with an array (even if it has only one element) preserves that dimension. In other words, scalar indices eliminate dimensions, and array indices retain them. To restore the previous behavior, where retrieving an index with an Array or Matrix with size 1 or a single value always returns the value itself regardless of index type, set the configuration option `{legacySubset: true}` using the `config` function.
+- If you use a scalar (single number) as an index for a dimension, that dimension is removed from the result.
+- If you use an array, matrix or range (even with just one element) as an index, that dimension is preserved in the result.
+
+This means that scalar indices eliminate dimensions, while array, matrix or range indices retain them. See the section [Migrate to v15](#migrate-to-v15) for more details and examples of this behavior.
 
 For example:
 
@@ -333,6 +333,38 @@ c.subset(math.index(1, [0, 1]), [2, 3])       // Matrix, [[0, 1], [2, 3]]
 e.resize([2, 3], 0)                           // Matrix, [[0, 0, 0], [0, 0, 0]]
 e.subset(math.index(1, 2), 5)                 // Matrix, [[0, 0, 0], [0, 0, 5]]
 ```
+## Migrate to v15
+
+With the release of math.js v15, the behavior of `subset` when indexing matrices and arrays has changed. If your code relies on the previous behavior (where indexing with an array or matrix of size 1 would always return the value itself), you may need to update your code or enable legacy mode.
+
+### How to migrate
+
+- **Option 1: Enable legacy behavior**  
+  If you want your code to work as before without changes, enable legacy mode by adding:
+  ```js
+  math.config({ legacySubset: true })
+  ```
+  This restores the old behavior for `subset`.
+
+- **Option 2: Update your code**  
+  Update your code to use scalar indices when you want to eliminate dimensions, or use array indices to preserve dimensions.
+
+### Migration examples
+
+```js
+const m = math.matrix([[10, 11, 12], [20, 21, 22]])
+```
+
+| Code example                       | v15+ (default) result         | v14- and v15+ (legacy mode) result | How to get old result in v15+.   |
+|------------------------------------|-------------------------------|------------------------------------|----------------------------------|
+| `m.subset(math.index(1, [2]))`     | `[22]`                        | `22`                               | Use `m.subset(math.index(1, 2))` |
+| `m.subset(math.index([1], 2))`     | `[22]`                        | `22`                               | Use `m.subset(math.index(1, 2))` |
+| `m.subset(math.index([1], [2]))`   | `[[22]]`                      | `22`                               | Use `m.subset(math.index(1, 2))` |
+| `m.subset(math.index(1, 2))`       | `22`                          | `22`                               | No change needed                 |
+
+> **Tip:**  
+> If you want to always get a scalar value, use scalar indices.
+> If you want to preserve dimensions, use array, matrix or range indices.
 
 ## Getting and setting a value in a matrix