From d0dcd9e851a16dbab1cbdd1b03f1f52c3b5c568f Mon Sep 17 00:00:00 2001 From: hannah Date: Thu, 11 Jan 2024 17:36:59 -0500 Subject: [PATCH] changed api changes to api guidelines and rearranged heirarchy a bit, added callout in coding guidelines to make more obvious. Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> --- doc/devel/api_changes.rst | 148 +++++++++++++++++++++---------------- doc/devel/coding_guide.rst | 9 +-- 2 files changed, 87 insertions(+), 70 deletions(-) diff --git a/doc/devel/api_changes.rst b/doc/devel/api_changes.rst index b0904077ee0c..52d52ecbd6da 100644 --- a/doc/devel/api_changes.rst +++ b/doc/devel/api_changes.rst @@ -1,7 +1,7 @@ .. _api_changes: -API changes -=========== +API guidelines +============== API consistency and stability are of great value; Therefore, API changes (e.g. signature changes, behavior changes, removals) will only be conducted @@ -17,67 +17,45 @@ are backwards-incompatible API changes. color_changes.rst -.. _api_whats_new: - -Announce changes, deprecations, and new features ------------------------------------------------- -When adding or changing the API in a backward in-compatible way, please add the -appropriate :ref:`versioning directive ` and document it -for the release notes and add the entry to the appropriate folder: +Add new API and features +------------------------ -+-------------------+-----------------------------+----------------------------------------------+ -| addition | versioning directive | announcement folder | -+===================+=============================+==============================================+ -| new feature | ``.. versionadded:: 3.N`` | :file:`doc/users/next_whats_new/` | -+-------------------+-----------------------------+----------------------------------------------+ -| API change | ``.. versionchanged:: 3.N`` | :file:`doc/api/next_api_changes/[kind]` | -+-------------------+-----------------------------+----------------------------------------------+ - -API deprecations are first introduced and then expired. During the introduction -period, users are warned that the API *will* change in the future. -During the expiration period, code is changed as described in the notice posted -during the introductory period. - -+-----------+--------------------------------------------------+----------------------------------------------+ -| stage | required changes | announcement folder | -+===========+==================================================+==============================================+ -| introduce | :ref:`introduce deprecation ` | :file:`doc/api/next_api_changes/deprecation` | -+-----------+--------------------------------------------------+----------------------------------------------+ -| expire | :ref:`expire deprecation ` | :file:`doc/api/next_api_changes/[kind]` | -+-----------+--------------------------------------------------+----------------------------------------------+ - -For both change notes and what's new, please avoid using references in section -titles, as it causes links to be confusing in the table of contents. Instead, -ensure that a reference is included in the descriptive text. - -API Change Notes -^^^^^^^^^^^^^^^^ +Every new function, parameter and attribute that is not explicitly marked as +private (i.e., starts with an underscore) becomes part of Matplotlib's public +API. As discussed above, changing the existing API is cumbersome. Therefore, +take particular care when adding new API: -.. include:: ../api/next_api_changes/README.rst - :start-line: 5 - :end-line: 31 +- Mark helper functions and internal attributes as private by prefixing them + with an underscore. +- Carefully think about good names for your functions and variables. +- Try to adopt patterns and naming conventions from existing parts of the + Matplotlib API. +- Consider making as many arguments keyword-only as possible. See also + `API Evolution the Right Way -- Add Parameters Compatibly`__. -What's new -^^^^^^^^^^ + __ https://emptysqua.re/blog/api-evolution-the-right-way/#adding-parameters -.. include:: ../users/next_whats_new/README.rst - :start-line: 5 - :end-line: 24 +.. _deprecation-guidelines: -Deprecation ------------ +Deprecate API +------------- API changes in Matplotlib have to be performed following the deprecation process below, except in very rare circumstances as deemed necessary by the development -team. This ensures that users are notified before the change will take effect -and thus prevents unexpected breaking of code. +team. Generally API deprecation happens in two stages: + +* **introduce:** warn users that the API *will* change +* **expire:** API *is* changed as described in the introduction period + +This ensures that users are notified before the change will take effect and thus +prevents unexpected breaking of code. Rules ^^^^^ -- Deprecations are targeted at the next point.release (e.g. 3.x) -- Deprecated API is generally removed two point-releases after introduction +- Deprecations are targeted at the next :ref:`minor release ` (e.g. 3.x) +- Deprecated API is generally removed (expired) two point-releases after introduction of the deprecation. Longer deprecations can be imposed by core developers on a case-by-case basis to give more time for the transition - The old API must remain fully functional during the deprecation period @@ -147,29 +125,44 @@ Expire deprecation instead. For removed items that were not in the stub file, only deleting from the allowlist is required. -Adding new API and features ---------------------------- -Every new function, parameter and attribute that is not explicitly marked as -private (i.e., starts with an underscore) becomes part of Matplotlib's public -API. As discussed above, changing the existing API is cumbersome. Therefore, -take particular care when adding new API: +.. redirect-from:: /devel/coding_guide#new-features-and-api-changes -- Mark helper functions and internal attributes as private by prefixing them - with an underscore. -- Carefully think about good names for your functions and variables. -- Try to adopt patterns and naming conventions from existing parts of the - Matplotlib API. -- Consider making as many arguments keyword-only as possible. See also - `API Evolution the Right Way -- Add Parameters Compatibly`__. +.. _api_whats_new: - __ https://emptysqua.re/blog/api-evolution-the-right-way/#adding-parameters +Announce new and deprecated API +------------------------------- + +When adding or changing the API in a backward in-compatible way, please add the +appropriate :ref:`versioning directive ` and document it +for the release notes and add the entry to the appropriate folder: + ++-------------------+-----------------------------+----------------------------------------------+ +| | versioning directive | announcement folder | ++===================+=============================+==============================================+ +| new feature | ``.. versionadded:: 3.N`` | :file:`doc/users/next_whats_new/` | ++-------------------+-----------------------------+----------------------------------------------+ +| API change | ``.. versionchanged:: 3.N`` | :file:`doc/api/next_api_changes/[kind]` | ++-------------------+-----------------------------+----------------------------------------------+ + +When deprecating API, please add a notice as described in the +:ref:`deprecation guidelines ` and summarized here: ++--------------------------------------------------+----------------------------------------------+ +| stage | announcement folder | ++===========+======================================+==============================================+ +| :ref:`introduce deprecation ` | :file:`doc/api/next_api_changes/deprecation` | ++-----------+--------------------------------------+----------------------------------------------+ +| :ref:`expire deprecation ` | :file:`doc/api/next_api_changes/[kind]` | ++-----------+--------------------------------------+----------------------------------------------+ + +Generally the introduction notices can be repurposed for the expiration notice as they +are expected to be describing the same API changes and removals. .. _versioning-directives: Versioning directives ---------------------- +^^^^^^^^^^^^^^^^^^^^^ When making a backward incompatible change, please add a versioning directive in the docstring. The directives should be placed at the end of a description block. @@ -209,3 +202,28 @@ For classes and functions, the directive should be placed before the *Parameters* section. For parameters, the directive should be placed at the end of the parameter description. The patch release version is omitted and the directive should not be added to entire modules. + +Release notes +^^^^^^^^^^^^^ + +For both change notes and what's new, please avoid using cross-references in section +titles as it causes links to be confusing in the table of contents. Instead, ensure that +a cross-reference is included in the descriptive text. + +.. _api-change-notes: + +API change notes +"""""""""""""""" + +.. include:: ../api/next_api_changes/README.rst + :start-line: 5 + :end-line: 31 + +.. _whats-new-notes: + +What's new notes +"""""""""""""""" + +.. include:: ../users/next_whats_new/README.rst + :start-line: 5 + :end-line: 24 diff --git a/doc/devel/coding_guide.rst b/doc/devel/coding_guide.rst index 6564de906979..05c63e43fe60 100644 --- a/doc/devel/coding_guide.rst +++ b/doc/devel/coding_guide.rst @@ -7,12 +7,11 @@ Coding guidelines We appreciate these guidelines being followed because it improves the readability, consistency, and maintainability of the code base. -API changes -=========== +.. admonition:: API guidelines + :class: seealso -If you are adding new features, changing behavior or function signatures, or -removing classes, functions, methods, or properties, please see the :ref:`api_changes` -guide. + If adding new features, changing behavior or function signatures, or removing + public interfaces, please consult the :ref:`api_changes`. PEP8, as enforced by flake8 ===========================