MNT: reorganize next_api again

jklymak · jklymak · commit 9828374f3205 · 2020-06-30T13:04:23.000-07:00
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -7,7 +7,7 @@
 - [ ] New features are documented, with examples if plot related
 - [ ] Documentation is sphinx and numpydoc compliant
 - [ ] Added an entry to doc/users/next_whats_new/ if major new feature (follow instructions in README.rst there)
-- [ ] Documented in doc/api/api_changes.rst if API changed in a backward-incompatible way
+- [ ] Documented in doc/api/next_api_changes/* if API changed in a backward-incompatible way
 
 <!--
 Thank you so much for your PR!  To help us review your contribution, please
diff --git a/doc/api/api_changes.rst b/doc/api/api_changes.rst
@@ -33,6 +33,9 @@ added to Matplotlib, see :ref:`whats-new`.
       :glob:
       :maxdepth: 1
 
-      api_changes_3.4/*
+      next_api_changes/behavior/*
+      next_api_changes/deprecations/*
+      next_api_changes/development/*
+      next_api_changes/removals/*
 
 .. include:: prev_api_changes/api_changes_3.3.0.rst
diff --git a/doc/api/api_changes_3.4/behaviour.rst b/doc/api/api_changes_3.4/behaviour.rst
diff --git a/doc/api/api_changes_3.4/development.rst b/doc/api/api_changes_3.4/development.rst
diff --git a/doc/api/api_changes_3.4/removals.rst b/doc/api/api_changes_3.4/removals.rst
diff --git a/doc/api/index.rst b/doc/api/index.rst
@@ -2,9 +2,8 @@ API Overview
 ============
 
 .. toctree::
-   :hidden:
 
-   api_changes
+   api_changes.rst
 
 .. contents:: :local:
 
diff --git a/doc/api/next_api_changes/README.rst b/doc/api/next_api_changes/README.rst
@@ -3,8 +3,8 @@
 Adding API change notes
 =======================
 
-API change notes for future releases are collected in the most recent directory
-:file:`api_changes_X.Y`. They are divided into four categories:
+API change notes for future releases are collected in
+:file:`next_api_changes`. They are divided into four subdirectories:
 
 - **Deprecations**: Announcements of future changes. Typically, these will
   raise a deprecation warning and users of this API should change their code
@@ -16,14 +16,15 @@ API change notes for future releases are collected in the most recent directory
   result.
 - **Development changes**: Changes to the build process, dependencies, etc.
 
-Please place new entries in the respective files in this directory. Typically,
-each change will get its own section, but you may also amend existing sections
-when suitable. The overall goal is a comprehensible documentation of the
-changes.
+Please place new entries in these directories with a new file named
+``99999-ABC.rst``, where ``99999`` would be the PR number, and ``ABC`` the
+author's initials. Typically, each change will get its own file, but you may
+also amend existing files when suitable. The overall goal is a comprehensible
+documentation of the changes.
 
 A typical entry could look like this::
 
-    Locators
-    ~~~~~~~~
-    The unused `Locator.autoscale()` method is deprecated (pass the axis
-    limits to `Locator.view_limits()` instead).
+   Locators
+   ~~~~~~~~
+   The unused `Locator.autoscale()` method is deprecated (pass the axis
+   limits to `Locator.view_limits()` instead).
diff --git a/doc/api/next_api_changes/behavior/00001-ABC.rst b/doc/api/next_api_changes/behavior/00001-ABC.rst
@@ -0,0 +1,7 @@
+Behavior Change template
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Enter description here....
+
+Please rename file with PR number and your initials i.e. "99999-ABC.rst"
+and ``git add`` the new file.  
diff --git a/doc/api/next_api_changes/deprecations/00001-ABC.rst b/doc/api/next_api_changes/deprecations/00001-ABC.rst
@@ -0,0 +1,7 @@
+Template for deprecations
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Add description here...
+
+Please rename file with PR number and your initials i.e. "99999-ABC.rst"
+and ``git add`` the new file.
diff --git a/doc/api/next_api_changes/deprecations/00009-AL.rst b/doc/api/next_api_changes/deprecations/00009-AL.rst
@@ -1,11 +1,7 @@
-Deprecations
-------------
-
 ``dpi_cor`` property of `.FancyArrowPatch`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 This parameter is considered internal and deprecated.
 
-
 Colorbar docstrings
 ~~~~~~~~~~~~~~~~~~~
 The following globals in :mod:`matplotlib.colorbar` are deprecated:
diff --git a/doc/api/next_api_changes/development/00001-ABC.rst b/doc/api/next_api_changes/development/00001-ABC.rst
@@ -0,0 +1,7 @@
+Development Change template
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Enter description here....
+
+Please rename file with PR number and your initials i.e. "99999-ABC.rst"
+and ``git add`` the new file.  
diff --git a/doc/api/next_api_changes/removals/00001-ABC.rst b/doc/api/next_api_changes/removals/00001-ABC.rst
@@ -0,0 +1,7 @@
+Removal Change template
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Enter description of methods/classes removed here....
+
+Please rename file with PR number and your initials i.e. "99999-ABC.rst"
+and ``git add`` the new file.  
diff --git a/doc/devel/coding_guide.rst b/doc/devel/coding_guide.rst
@@ -110,8 +110,9 @@ Documentation
   :file:`doc/users/whats_new.rst`.
 
 * If you change the API in a backward-incompatible way, please
-  document it in the relevant file in most recent
-  :file:`doc/api/api_changes_X.Y`.
+  document it by adding a file in the relevant subdirectory of
+  :file:`doc/api/next_api_changes/`, probably in the ``behaviour/``
+  subdirectory.
 
 .. _pr-labels:
 
@@ -163,9 +164,9 @@ Merging
   approve the review and if you think no more review is needed, merge
   the PR.
 
-  Ensure that all API changes are documented in the relevant file in
-  the most recent :file:`doc/api/api_changes_X.Y` and significant new features
-  have an entry in :file:`doc/user/whats_new`.
+  Ensure that all API changes are documented in a file in one of the
+  subdirectories of :file:`doc/api/next_api_changes`, and significant new
+  features have an entry in :file:`doc/user/whats_new`.
 
   - If a PR already has a positive review, a core developer (e.g. the first
     reviewer, but not necessarily) may champion that PR for merging.  In order
diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst
@@ -227,8 +227,10 @@ 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
-  :file:`doc/api/api_changes`, by adding to the relevant file
-  (see :file:`doc/api/api_changes.rst` for more information)
+  :file:`doc/api/next_api_changes/behaviour`, by adding a new file with the
+  naming convention ``99999-ABC.rst`` where the pull request number is followed
+  by the contributor's initials. (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.
@@ -317,8 +319,10 @@ API changes
 Changes to the public API must follow a standard deprecation procedure to
 prevent unexpected breaking of code that uses Matplotlib.
 
-- Deprecations must be announced via an entry in
-  the most recent :file:`doc/api/api_changes_X.Y`
+- Deprecations must be announced via a new file in
+  a new file in :file:`doc/api/next_api_changes/deprecations/` with
+  naming convention ``99999-ABC.rst`` where ``99999`` is the pull request
+  number and ``ABC`` are the contributor's initials.
 - Deprecations are targeted at the next point-release (i.e. 3.x.0).
 - The deprecated API should, to the maximum extent possible, remain fully
   functional during the deprecation period. In cases where this is not
diff --git a/doc/devel/release_guide.rst b/doc/devel/release_guide.rst
@@ -112,7 +112,7 @@ For the "what's new",
 Similarly for the "API changes",
 
  1. copy the current api changes to a file is :file:`doc/api/prev_api_changes`
- 2. merge all of the files in the most recent :file:`doc/api/api_changes_X.Y`
+ 2. merge all of the files in the most recent :file:`doc/api/next_api_changes`
     into :file:`doc/api/api_changes.rst`
  3. comment out the most recent API changes at the top.
 
