From 92ee55dff1e11e10e19c3914b459d685cb50f57e Mon Sep 17 00:00:00 2001 From: sveneschlbeck Date: Sat, 13 Nov 2021 12:57:19 +0100 Subject: [PATCH 1/6] Added the definition of Deprecation and made Deprecation Process clearer --- doc/devel/contributing.rst | 47 +++++++++++++++++++++++--------------- 1 file changed, 29 insertions(+), 18 deletions(-) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index d20c23306243..95ce89e8f6af 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -288,26 +288,37 @@ 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 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 - possible, the deprecation must never make a given piece of code do something - different than it was before; at least an exception should be raised. -- If possible, usage of an deprecated API should emit a - `.MatplotlibDeprecationWarning`. There are a number of helper tools for this: - - - Use ``_api.warn_deprecated()`` for general deprecation warnings. - - Use the decorator ``@_api.deprecated`` to deprecate classes, functions, +- Definition of Deprecation + - Deprecations are Announcements of future changes, stating that the status + quo will be outdated in the future and replaced by a new standard + - Users are advised to change their code in order to guarantee compatibility + with future Matplotlib releases. + - The Deprecation date is marked by the ``since`` argument, specifying from + which release forward the argument is or was deprecated. The Deprecation + date is not to be confused with the ``removal`` argument, specifying from + which release forward the argument will be removed. + +- Deprecation Process + - 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 + possible, the deprecation must never make a given piece of code do something + different than it was before; at least an exception should be raised. + - If possible, usage of a deprecated API should emit a + `.MatplotlibDeprecationWarning`. There are a number of helper tools for this: + + - Use ``_api.warn_deprecated()`` for general deprecation warnings. + - Use the decorator ``@_api.deprecated`` to deprecate classes, functions, methods, or properties. - - To warn on changes of the function signature, use the decorators - ``@_api.delete_parameter``, ``@_api.rename_parameter``, and - ``@_api.make_keyword_only``. + - To warn on changes of the function signature, use the decorators + ``@_api.delete_parameter``, ``@_api.rename_parameter``, and + ``@_api.make_keyword_only``. -- Deprecated API may be removed two point-releases after they were deprecated. + - Deprecated API may be removed two point-releases after they were deprecated. Adding new API From 7a67b78191cc9700b77fe7af2cfefa82d5441010 Mon Sep 17 00:00:00 2001 From: Sven Eschlbeck <66701689+sveneschlbeck@users.noreply.github.com> Date: Sat, 13 Nov 2021 23:06:25 +0100 Subject: [PATCH 2/6] Update contributing.rst --- doc/devel/contributing.rst | 54 ++++++++++++++++++++++---------------- 1 file changed, 31 insertions(+), 23 deletions(-) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index 95ce89e8f6af..4dd85f664c05 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -285,8 +285,12 @@ Coding guidelines API changes ----------- -Changes to the public API must follow a standard deprecation procedure to -prevent unexpected breaking of code that uses Matplotlib. +Generally, API consistency and stability are of great value. Therefore, API +changes (e.g. Removals, Behavior Changes) should only be conducted if the +resulting value is worth the effort. Deprecating an API before changing it +(marking it as outdated) is therefore mandatory and done in accordance with +a standard Deprecation procedure to prevent unexpected breaking of code that +uses Matplotlib. - Definition of Deprecation - Deprecations are Announcements of future changes, stating that the status @@ -299,27 +303,31 @@ prevent unexpected breaking of code that uses Matplotlib. which release forward the argument will be removed. - Deprecation Process - - 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 - possible, the deprecation must never make a given piece of code do something - different than it was before; at least an exception should be raised. - - If possible, usage of a deprecated API should emit a - `.MatplotlibDeprecationWarning`. There are a number of helper tools for this: - - - Use ``_api.warn_deprecated()`` for general deprecation warnings. - - Use the decorator ``@_api.deprecated`` to deprecate classes, functions, - methods, or properties. - - To warn on changes of the function signature, use the decorators - ``@_api.delete_parameter``, ``@_api.rename_parameter``, and - ``@_api.make_keyword_only``. - - - Deprecated API may be removed two point-releases after they were deprecated. - + - Rules + - Deprecations are targeted at the next point.release (e.g. 3.x.0) + - Deprecated API may be removed two point-releases after their initial + Deprecation + - The old API must remain fully functional during the Deprecation period + - If valid alternatives to the deprecated API exist, they should be available + during the Deprecation period + - If in doubt, decisions about API changes are finally made by the + API consistency lead developer + - Process Schema + 1. Deprecation Announcement 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 + 2. Deprecations are then targeted at the next point-release (e.g. 3.x.0) + 3. The continuing usage of a deprecated API should result in a + Runtime Warming (`.MatplotlibDeprecationWarning`). There are a number + of helper tools for this: + - Use ``_api.warn_deprecated()`` for general deprecation warnings + - Use the decorator ``@_api.deprecated`` to deprecate classes, functions, + methods, or properties + - To warn on changes of the function signature, use the decorators + ``@_api.delete_parameter``, ``@_api.rename_parameter``, and + ``@_api.make_keyword_only`` + 4. Deprecated API gets removed two point-releases after initial Deprecation Adding new API -------------- From 2625d32a728988799bf925842b6531d8841fe439 Mon Sep 17 00:00:00 2001 From: Sven Eschlbeck <66701689+sveneschlbeck@users.noreply.github.com> Date: Mon, 15 Nov 2021 09:02:36 +0100 Subject: [PATCH 3/6] Update doc/devel/contributing.rst Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> --- doc/devel/contributing.rst | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index 4dd85f664c05..258f2d81518a 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -285,12 +285,13 @@ Coding guidelines API changes ----------- -Generally, API consistency and stability are of great value. Therefore, API -changes (e.g. Removals, Behavior Changes) should only be conducted if the -resulting value is worth the effort. Deprecating an API before changing it -(marking it as outdated) is therefore mandatory and done in accordance with -a standard Deprecation procedure to prevent unexpected breaking of code that -uses Matplotlib. +API consistency and stability are of great value. Therefore, API changes +(e.g. signature changes, behavior changes, removals) will only be conducted +if the added benefit is worth the user effort for adapting. + +All API changes in Matplotlib have to be performed following the below +deprecation process. This ensures that users are notified before the change +will take effect and thus prevents unexpected breaking of code. - Definition of Deprecation - Deprecations are Announcements of future changes, stating that the status From 88fadaacee7869fba6420aae55472c55cc893be1 Mon Sep 17 00:00:00 2001 From: Sven Eschlbeck <66701689+sveneschlbeck@users.noreply.github.com> Date: Mon, 15 Nov 2021 09:02:46 +0100 Subject: [PATCH 4/6] Update doc/devel/contributing.rst Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> --- doc/devel/contributing.rst | 79 +++++++++++++++++++++----------------- 1 file changed, 43 insertions(+), 36 deletions(-) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index 258f2d81518a..1c24a96c751a 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -293,42 +293,49 @@ All API changes in Matplotlib have to be performed following the below deprecation process. This ensures that users are notified before the change will take effect and thus prevents unexpected breaking of code. -- Definition of Deprecation - - Deprecations are Announcements of future changes, stating that the status - quo will be outdated in the future and replaced by a new standard - - Users are advised to change their code in order to guarantee compatibility - with future Matplotlib releases. - - The Deprecation date is marked by the ``since`` argument, specifying from - which release forward the argument is or was deprecated. The Deprecation - date is not to be confused with the ``removal`` argument, specifying from - which release forward the argument will be removed. - -- Deprecation Process - - Rules - - Deprecations are targeted at the next point.release (e.g. 3.x.0) - - Deprecated API may be removed two point-releases after their initial - Deprecation - - The old API must remain fully functional during the Deprecation period - - If valid alternatives to the deprecated API exist, they should be available - during the Deprecation period - - If in doubt, decisions about API changes are finally made by the - API consistency lead developer - - Process Schema - 1. Deprecation Announcement 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 - 2. Deprecations are then targeted at the next point-release (e.g. 3.x.0) - 3. The continuing usage of a deprecated API should result in a - Runtime Warming (`.MatplotlibDeprecationWarning`). There are a number - of helper tools for this: - - Use ``_api.warn_deprecated()`` for general deprecation warnings - - Use the decorator ``@_api.deprecated`` to deprecate classes, functions, - methods, or properties - - To warn on changes of the function signature, use the decorators - ``@_api.delete_parameter``, ``@_api.rename_parameter``, and - ``@_api.make_keyword_only`` - 4. Deprecated API gets removed two point-releases after initial Deprecation +Deprecation process +~~~~~~~~~~~~~~~~~~~ + +Rules: + +- Deprecations are targeted at the next point.release (e.g. 3.x) +- Deprecated API is generally removed two 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 +- If alternatives to the deprecated API exist, they should be available + during the deprecation period +- If in doubt, decisions about API changes are finally made by the + API consistency lead developer + +Introducing a deprecation: + +1. Announce the deprecation in a new file + :file:`doc/api/next_api_changes/deprecations/99999-ABC.rst` where ``99999`` + is the pull request number and ``ABC`` are the contributor's initials. +2. If possible, issue a `.MatplotlibDeprecationWarning` when the deprecated + API is used. There are a number of helper tools for this: + + - Use ``_api.warn_deprecated()`` for general deprecation warnings + - Use the decorator ``@_api.deprecated`` to deprecate classes, functions, + methods, or properties + - To warn on changes of the function signature, use the decorators + ``@_api.delete_parameter``, ``@_api.rename_parameter``, and + ``@_api.make_keyword_only`` + + All these helpers take a first parameter *since*, which should be set to + the next point release, e.g. "3.x". + +Expiring a deprecation: + +1. Announce the API changes in a new file + :file:`doc/api/next_api_changes/[kind]/99999-ABC.rst` where ``99999`` + is the pull request number and ``ABC`` are the contributor's initials, and + ``[kind]`` is one of the folders :file:`behavior`, :file:`development`, + :file:`removals`. See :file:`doc/api/next_api_changes/README.rst` for more + information. For the content, you can usually copy the deprecation notice + and adapt it slightly. +2. Change the code functionality and remove any related deprecation warnings. Adding new API -------------- From 3a134aa8f5cf1e342d33bfc57c612b906b4a2bca Mon Sep 17 00:00:00 2001 From: Sven Eschlbeck <66701689+sveneschlbeck@users.noreply.github.com> Date: Mon, 15 Nov 2021 09:24:43 +0000 Subject: [PATCH 5/6] Update contributing.rst Introduced more specific subsection titles since it is obvious that all refer to Deprecations --- doc/devel/contributing.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index 1c24a96c751a..d84461de2b0e 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -293,10 +293,8 @@ All API changes in Matplotlib have to be performed following the below deprecation process. This ensures that users are notified before the change will take effect and thus prevents unexpected breaking of code. -Deprecation process -~~~~~~~~~~~~~~~~~~~ - -Rules: +Rules +~~~~~ - Deprecations are targeted at the next point.release (e.g. 3.x) - Deprecated API is generally removed two two point-releases after introduction @@ -308,7 +306,8 @@ Rules: - If in doubt, decisions about API changes are finally made by the API consistency lead developer -Introducing a deprecation: +Introducing +~~~~~~~~~~~ 1. Announce the deprecation in a new file :file:`doc/api/next_api_changes/deprecations/99999-ABC.rst` where ``99999`` @@ -326,7 +325,8 @@ Introducing a deprecation: All these helpers take a first parameter *since*, which should be set to the next point release, e.g. "3.x". -Expiring a deprecation: +Expiring +~~~~~~~~ 1. Announce the API changes in a new file :file:`doc/api/next_api_changes/[kind]/99999-ABC.rst` where ``99999`` From 3622b7cecece348bc1468ddf6367d2819b3cb608 Mon Sep 17 00:00:00 2001 From: Sven Eschlbeck <66701689+sveneschlbeck@users.noreply.github.com> Date: Mon, 15 Nov 2021 10:01:00 +0000 Subject: [PATCH 6/6] Update contributing.rst Adding sentence saying that rare cases might need lead dev attention --- doc/devel/contributing.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index d84461de2b0e..b4d732d6ac3d 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -289,9 +289,10 @@ API consistency and stability are of great value. Therefore, API changes (e.g. signature changes, behavior changes, removals) will only be conducted if the added benefit is worth the user effort for adapting. -All API changes in Matplotlib have to be performed following the below -deprecation process. This ensures that users are notified before the change -will take effect and thus prevents unexpected breaking of code. +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. Rules ~~~~~