add api change docs

Author: saranti

doc/api/next_api_changes/behavior/28363-TS.rst

@@ -0,0 +1,6 @@
+Subfigures
+~~~~~~~~~~
+
+`.Figure.subfigures` are now added in row-major order to be consistent with
+`.Figure.subplots`.  The return value of `~.Figure.subfigures` is not changed,
+but the order of ``fig.subfigs`` is.

doc/users/next_whats_new/subfigures_change_order.rst

@@ -0,0 +1,23 @@
+Subfigures are now added in row-major order
+-------------------------------------------
+
+``Figure.subfigures`` are now added in row-major order for API consistency.
+
+
+.. plot::
+    :include-source: true
+    :alt: Example of creating 3 by 3 subfigures.
+
+    import matplotlib.pyplot as plt
+
+    fig = plt.figure()
+    subfigs = fig.subfigures(3, 3)
+    x = np.linspace(0, 10, 100)
+
+    for i, sf in enumerate(fig.subfigs):
+        ax = sf.subplots()
+        ax.plot(x, np.sin(x + i), label=f'Subfigure {i+1}')
+        sf.suptitle(f'Subfigure {i+1}')
+        ax.set_xticks([])
+        ax.set_yticks([])
+    plt.show()

lib/matplotlib/figure.py

@@ -1550,6 +1550,9 @@ def subfigures(self, nrows=1, ncols=1, squeeze=True,
         .. note::
             The *subfigure* concept is new in v3.4, and the API is still provisional.
 
+        .. versionchanged:: 3.10
+            subfigures are now added in row-major order.
+
         Parameters
         ----------
         nrows, ncols : int, default: 1

lib/matplotlib/tests/test_figure.py

@@ -1735,12 +1735,9 @@ def test_warn_colorbar_mismatch():
         subfig3_1.colorbar(im4_1)
 
 
-@check_figures_equal(extensions=['png'])
-def test_subfigure_row_order(fig_test, fig_ref):
-    # Test that subfigures are drawn in row major order.
-    sf_arr_ref = fig_ref.subfigures(4, 3)
-    for i, sf in enumerate(sf_arr_ref.ravel()):
-        sf.suptitle(i)
-    fig_test.subfigures(4, 3)
-    for i, sf in enumerate(fig_test.subfigs):
-        sf.suptitle(i)
+def test_subfigure_row_order():
+    # Test that subfigures are drawn in row-major order.
+    fig = plt.figure()
+    sf_arr = fig.subfigures(4, 3)
+    for a, b in zip(sf_arr.ravel(), fig.subfigs):
+        assert a is b