Merge pull request matplotlib#15158 from dstansby/apichanges

Change the way API changes are documented

Author: jklymak

doc/api/api_changes.rst

@@ -25,7 +25,7 @@ added to Matplotlib, see :ref:`whats-new`.
 
       When a release is made
 
-       - All the files in 'next_api_changes/' should be moved to a single file in
+       - The files in 'next_api_changes/' should be moved to a new file in
          'prev_api_changes/'.
        - The include directive below should be changed to point to the new file
          created in the previous step.

doc/api/next_api_changes/behaviour.rst

@@ -0,0 +1,2 @@
+Behaviour changes
+-----------------

doc/api/next_api_changes/deprecations.rst

@@ -0,0 +1,2 @@
+Deprecations
+------------

doc/api/next_api_changes/development.rst

@@ -0,0 +1,2 @@
+Development changes
+-------------------

doc/api/next_api_changes/removals.rst

@@ -0,0 +1,2 @@
+Removals
+--------

doc/devel/coding_guide.rst

@@ -89,7 +89,7 @@ Documentation
   :file:`doc/users/whats_new.rst`.
 
 * If you change the API in a backward-incompatible way, please
-  document it in :file:`doc/api/api_changes.rst`.
+  document it in the relevant file in :file:`doc/api/next_api_changes`.
 
 .. _pr-labels:
 
@@ -138,8 +138,8 @@ Merging
   approve the review and if you think no more review is needed, merge
   the PR.
 
-  Ensure that all API changes are documented in
-  :file:`doc/api/api_changes` and significant new features have and
+  Ensure that all API changes are documented in the relevant file in
+  :file:`doc/api/next_api_changes` and significant new features have and
   entry in :file:`doc/user/whats_new`.
 
   - If a PR already has a positive review, a core developer (e.g. the first

doc/devel/contributing.rst

@@ -267,8 +267,8 @@ rules before submitting a pull request:
   :file:`doc/users/next_whats_new/README.rst` for more information).
 
 * If you change the API in a backward-incompatible way, please document it in
-  `doc/api/api_changes`, by adding a new file describing your changes (see
-  :file:`doc/api/api_changes/README.rst` for more information)
+  :file:`doc/api/api_changes`, by adding to the relevant file
+  (see :file:`doc/api/api_changes.rst` for more information)
 
 * See below for additional points about :ref:`keyword-argument-processing`, if
   applicable for your pull request.