From bbe15b9740ef75f5854b96267e04272798de45c5 Mon Sep 17 00:00:00 2001 From: Abdulaziz Aloqeely <52792999+Aloqeely@users.noreply.github.com> Date: Thu, 27 Jun 2024 22:05:13 +0300 Subject: [PATCH 01/10] PDEP-17: Backwards compatibility and deprecation policy --- ...ds-compatibility-and-deprecation-policy.md | 84 +++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md diff --git a/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md b/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md new file mode 100644 index 0000000000000..9000ba42d4259 --- /dev/null +++ b/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md @@ -0,0 +1,84 @@ +# PDEP-17: Backwards compatibility and deprecation policy + +- Created: June 2024 +- Status: Under discussion +- Discussion: +- Author: [Abdulaziz Aloqeely](https://github.com/Aloqeely) +- Revision: 1 + +## Abstract + +This PDEP defines pandas' backwards compatibility and deprecation policy. + +## Motivation + +Having a clear backwards compatibility and deprecation policy is crucial to having a healthy ecosystem. We want to ensure users can rely on pandas being stable while still allowing the library to evolve. + +This policy will ensure that users have enough time to deal with deprecations while also minimizing disruptions on downstream packages' users. + +## Scope + +This PDEP covers pandas' approach to backwards compatibility and the deprecation and removal process. + +The decision making process for deprecating features is out of scope for this PDEP. + +## Background + +pandas uses a loose variant of semantic versioning. +A pandas release number is written in the format of ``MAJOR.MINOR.PATCH``. + +For the purposes of this PDEP, the last minor release before a major release will be referred to as the 'final minor version'. + +## General policy + +This policy applies to the public API. Anything not part of the public API or is marked as "Experimental" may be changed or removed at anytime. + +- Breaking backwards compatibility should benefit more than it harms users. +- Breaking changes should go through a deprecation cycle before being implemented. +- Breaking changes should only occur in major releases. +- No deprecations should be introduced in patch releases. + +Some bug fixes may require breaking backwards compatibility. In these cases, a deprecation cycle is not necessary. However, bug fixes which have a large impact on users might be treated as a breaking change. Whether or not a change is a bug fix or an API breaking change is a judgement call. + +## Deprecation process + +Whenever there are plans to break backwards compatibility, a deprecation must be introduced. The deprecation will preserve the existing behavior while emitting a warning that the behavior will be changing in a future version. + +A deprecation's warning message should: +- Provide information on what is changing. +- Mention how to achieve similar behavior if an alternative is available. +- Include the version in which the deprecation will be enforced. +- For large-scale deprecations, it is recommended include a reason for the deprecation, alongside a discussion link to get user feedback. + +Additionally, when one introduces a deprecation, they should: +- Use the appropriate warning class. More info on this can be found below. +- Add the GitHub issue/PR number as a comment above the warning line. +- Add an entry in the release notes. +- Mention that the functionality is deprecated in the documentation using the ``.. deprecated::`` directive. + +### Which warning class to use + +Deprecations should initially use ``DeprecationWarning``, and then be switched to ``FutureWarning`` for broader visibility in the final minor version before the major release they are planned to be removed in. +This implementation detail can be ignored by using the appropriate ``PandasDeprecationWarning`` variable. + +Not all deprecations have to use ``DeprecationWarning`` but all deprecations should eventually transition to ``FutureWarning``, i.e. deprecations in the final minor version which are planned to be removed in the major release after will immediately use ``FutureWarning``. + +It is recommended to not introduce large-scale deprecations in the final minor version which are planned to be removed in the major release after, since that will immediately be using a loud ``FutureWarning`` with not much time between deprecation and removal. Instead, a ``DeprecationWarning`` should be used, and the removal should be scheduled for a later major release. + +### Support window for the final minor version + +Defining a release policy is not part of this PDEP's scope, but, the final minor version plays a special role in deprecations, since: +- It is the version where deprecations planned for removal in the next major release get switched from a ``DeprecationWarning`` to a more visible ``FutureWarning``. +- ``FutureWarning`` deprecations released in it will immediately be removed in the next major release. + +And so, this document recommends a minimum of 6 months between the final minor version and the next major release. + +### Enforcement of deprecations + +When one enforces a deprecation, they should: +- Add an entry in the release notes. +- Replace the ``.. deprecated::`` directive in the documentation with a ``.. versioncchanged::`` directive. + +### PDEP-17 History + +- June 2024: Initial version. From 2c9657b13ec054efdc23aacd419e017b9479aeb0 Mon Sep 17 00:00:00 2001 From: Abdulaziz Aloqeely <52792999+Aloqeely@users.noreply.github.com> Date: Thu, 27 Jun 2024 22:15:58 +0300 Subject: [PATCH 02/10] Final revision --- ...0017-backwards-compatibility-and-deprecation-policy.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md b/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md index 9000ba42d4259..326f1d2d176fb 100644 --- a/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md +++ b/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md @@ -1,8 +1,8 @@ # PDEP-17: Backwards compatibility and deprecation policy -- Created: June 2024 +- Created: 27 June 2024 - Status: Under discussion -- Discussion: +- Discussion: [#59125](https://github.com/pandas-dev/pandas/issues/59125) - Author: [Abdulaziz Aloqeely](https://github.com/Aloqeely) - Revision: 1 @@ -71,7 +71,7 @@ Defining a release policy is not part of this PDEP's scope, but, the final minor - It is the version where deprecations planned for removal in the next major release get switched from a ``DeprecationWarning`` to a more visible ``FutureWarning``. - ``FutureWarning`` deprecations released in it will immediately be removed in the next major release. -And so, this document recommends a minimum of 6 months between the final minor version and the next major release. +And so, this document recommends a minimum of 6 months between the final minor version and the major release after it. ### Enforcement of deprecations @@ -81,4 +81,4 @@ When one enforces a deprecation, they should: ### PDEP-17 History -- June 2024: Initial version. +- 27 June 2024: Initial version. From a2476e55f8319462cc8c25b6384a4f4f2d88b54d Mon Sep 17 00:00:00 2001 From: Abdulaziz Aloqeely <52792999+Aloqeely@users.noreply.github.com> Date: Fri, 5 Jul 2024 16:14:29 +0300 Subject: [PATCH 03/10] resolve contradiction --- .../0017-backwards-compatibility-and-deprecation-policy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md b/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md index 326f1d2d176fb..fa354f5a131e4 100644 --- a/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md +++ b/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md @@ -42,7 +42,7 @@ Some bug fixes may require breaking backwards compatibility. In these cases, a d ## Deprecation process -Whenever there are plans to break backwards compatibility, a deprecation must be introduced. The deprecation will preserve the existing behavior while emitting a warning that the behavior will be changing in a future version. +Deprecation provides a way to warn developers and give them time to adapt their code to the new functionality before the old behavior is eventually removed. A deprecation's warning message should: - Provide information on what is changing. From 58d34e0e409d77b58b97445e9b8dfad6fc9dd9ff Mon Sep 17 00:00:00 2001 From: Abdulaziz Aloqeely <52792999+Aloqeely@users.noreply.github.com> Date: Fri, 5 Jul 2024 16:35:34 +0300 Subject: [PATCH 04/10] Link to public API reference --- .../0017-backwards-compatibility-and-deprecation-policy.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md b/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md index fa354f5a131e4..2aad7abe8d44b 100644 --- a/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md +++ b/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md @@ -31,7 +31,7 @@ For the purposes of this PDEP, the last minor release before a major release wil ## General policy -This policy applies to the public API. Anything not part of the public API or is marked as "Experimental" may be changed or removed at anytime. +This policy applies to the [public API][1]. Anything not part of the [public API][1] or is marked as "Experimental" may be changed or removed at anytime. - Breaking backwards compatibility should benefit more than it harms users. - Breaking changes should go through a deprecation cycle before being implemented. @@ -82,3 +82,5 @@ When one enforces a deprecation, they should: ### PDEP-17 History - 27 June 2024: Initial version. + +[1]: https://pandas.pydata.org/docs/reference/index.html From 7c5be2a1005a36ebe3531367369cebaeeb4da188 Mon Sep 17 00:00:00 2001 From: Abdulaziz Aloqeely <52792999+Aloqeely@users.noreply.github.com> Date: Fri, 9 Aug 2024 18:34:20 +0300 Subject: [PATCH 05/10] Review Co-authored-by: Irv Lustig --- .../0017-backwards-compatibility-and-deprecation-policy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md b/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md index 2aad7abe8d44b..65ceaf3ade287 100644 --- a/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md +++ b/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md @@ -48,7 +48,7 @@ A deprecation's warning message should: - Provide information on what is changing. - Mention how to achieve similar behavior if an alternative is available. - Include the version in which the deprecation will be enforced. -- For large-scale deprecations, it is recommended include a reason for the deprecation, alongside a discussion link to get user feedback. +- For large-scale deprecations, it is recommended to include a reason for the deprecation, alongside a discussion link to get user feedback. Additionally, when one introduces a deprecation, they should: - Use the appropriate warning class. More info on this can be found below. From 607ef541cfeb732e8d889c457e4164a7e957d4e2 Mon Sep 17 00:00:00 2001 From: Abdulaziz Aloqeely <52792999+Aloqeely@users.noreply.github.com> Date: Fri, 9 Aug 2024 18:43:11 +0300 Subject: [PATCH 06/10] explain variable --- .../0017-backwards-compatibility-and-deprecation-policy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md b/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md index 65ceaf3ade287..9c04d650142f7 100644 --- a/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md +++ b/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md @@ -59,7 +59,7 @@ Additionally, when one introduces a deprecation, they should: ### Which warning class to use Deprecations should initially use ``DeprecationWarning``, and then be switched to ``FutureWarning`` for broader visibility in the final minor version before the major release they are planned to be removed in. -This implementation detail can be ignored by using the appropriate ``PandasDeprecationWarning`` variable. +This implementation detail can be ignored by using the appropriate ``PandasDeprecationWarning`` variable, which will be aliased to the proper warning class based on the pandas version. Not all deprecations have to use ``DeprecationWarning`` but all deprecations should eventually transition to ``FutureWarning``, i.e. deprecations in the final minor version which are planned to be removed in the major release after will immediately use ``FutureWarning``. From 5493e317c1177adbef5780d71d48c1627bed0c2a Mon Sep 17 00:00:00 2001 From: Abdulaziz Aloqeely <52792999+Aloqeely@users.noreply.github.com> Date: Wed, 4 Sep 2024 19:52:38 +0300 Subject: [PATCH 07/10] address review --- ...ds-compatibility-and-deprecation-policy.md | 21 +++++-------------- 1 file changed, 5 insertions(+), 16 deletions(-) diff --git a/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md b/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md index 9c04d650142f7..af81fc1562af8 100644 --- a/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md +++ b/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md @@ -20,15 +20,11 @@ This policy will ensure that users have enough time to deal with deprecations wh This PDEP covers pandas' approach to backwards compatibility and the deprecation and removal process. -The decision making process for deprecating features is out of scope for this PDEP. - ## Background pandas uses a loose variant of semantic versioning. A pandas release number is written in the format of ``MAJOR.MINOR.PATCH``. -For the purposes of this PDEP, the last minor release before a major release will be referred to as the 'final minor version'. - ## General policy This policy applies to the [public API][1]. Anything not part of the [public API][1] or is marked as "Experimental" may be changed or removed at anytime. @@ -37,6 +33,7 @@ This policy applies to the [public API][1]. Anything not part of the [public API - Breaking changes should go through a deprecation cycle before being implemented. - Breaking changes should only occur in major releases. - No deprecations should be introduced in patch releases. +- Deprecated functionality should remain unchanged for at least 6 months before being changed or removed. Some bug fixes may require breaking backwards compatibility. In these cases, a deprecation cycle is not necessary. However, bug fixes which have a large impact on users might be treated as a breaking change. Whether or not a change is a bug fix or an API breaking change is a judgement call. @@ -58,26 +55,18 @@ Additionally, when one introduces a deprecation, they should: ### Which warning class to use -Deprecations should initially use ``DeprecationWarning``, and then be switched to ``FutureWarning`` for broader visibility in the final minor version before the major release they are planned to be removed in. +Deprecations should initially use ``DeprecationWarning``, and then be switched to ``FutureWarning`` for broader visibility in the last minor release before the major release they are planned to be removed in. This implementation detail can be ignored by using the appropriate ``PandasDeprecationWarning`` variable, which will be aliased to the proper warning class based on the pandas version. -Not all deprecations have to use ``DeprecationWarning`` but all deprecations should eventually transition to ``FutureWarning``, i.e. deprecations in the final minor version which are planned to be removed in the major release after will immediately use ``FutureWarning``. - -It is recommended to not introduce large-scale deprecations in the final minor version which are planned to be removed in the major release after, since that will immediately be using a loud ``FutureWarning`` with not much time between deprecation and removal. Instead, a ``DeprecationWarning`` should be used, and the removal should be scheduled for a later major release. - -### Support window for the final minor version - -Defining a release policy is not part of this PDEP's scope, but, the final minor version plays a special role in deprecations, since: -- It is the version where deprecations planned for removal in the next major release get switched from a ``DeprecationWarning`` to a more visible ``FutureWarning``. -- ``FutureWarning`` deprecations released in it will immediately be removed in the next major release. +Not all deprecations have to use ``DeprecationWarning`` but all deprecations should eventually transition to ``FutureWarning``, i.e. deprecations in the last minor release which are planned to be removed in the major release after will immediately use ``FutureWarning``. -And so, this document recommends a minimum of 6 months between the final minor version and the major release after it. +It is recommended to not introduce large-scale deprecations in the last minor release which are planned to be removed in the major release after, since that will immediately be using a loud ``FutureWarning`` with not much time between deprecation and removal. Instead, a ``DeprecationWarning`` should be used, and the removal should be scheduled for a later major release. ### Enforcement of deprecations When one enforces a deprecation, they should: - Add an entry in the release notes. -- Replace the ``.. deprecated::`` directive in the documentation with a ``.. versioncchanged::`` directive. +- For API changes, replace the ``.. deprecated::`` directive in the documentation with a ``.. versionchanged::`` directive. ### PDEP-17 History From 0a053482e2a80fef2286be03e33e150d8867422b Mon Sep 17 00:00:00 2001 From: Abdulaziz Aloqeely <52792999+Aloqeely@users.noreply.github.com> Date: Wed, 18 Sep 2024 13:38:10 +0300 Subject: [PATCH 08/10] More reviews --- ...017-backwards-compatibility-and-deprecation-policy.md | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md b/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md index af81fc1562af8..9c246dd89a63b 100644 --- a/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md +++ b/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md @@ -30,10 +30,10 @@ A pandas release number is written in the format of ``MAJOR.MINOR.PATCH``. This policy applies to the [public API][1]. Anything not part of the [public API][1] or is marked as "Experimental" may be changed or removed at anytime. - Breaking backwards compatibility should benefit more than it harms users. -- Breaking changes should go through a deprecation cycle before being implemented. +- Breaking changes should go through a deprecation cycle before being implemented if possible. - Breaking changes should only occur in major releases. - No deprecations should be introduced in patch releases. -- Deprecated functionality should remain unchanged for at least 6 months before being changed or removed. +- Deprecated functionality should remain unchanged in at least 2 minor releases before being changed or removed. Some bug fixes may require breaking backwards compatibility. In these cases, a deprecation cycle is not necessary. However, bug fixes which have a large impact on users might be treated as a breaking change. Whether or not a change is a bug fix or an API breaking change is a judgement call. @@ -44,7 +44,6 @@ Deprecation provides a way to warn developers and give them time to adapt their A deprecation's warning message should: - Provide information on what is changing. - Mention how to achieve similar behavior if an alternative is available. -- Include the version in which the deprecation will be enforced. - For large-scale deprecations, it is recommended to include a reason for the deprecation, alongside a discussion link to get user feedback. Additionally, when one introduces a deprecation, they should: @@ -58,10 +57,6 @@ Additionally, when one introduces a deprecation, they should: Deprecations should initially use ``DeprecationWarning``, and then be switched to ``FutureWarning`` for broader visibility in the last minor release before the major release they are planned to be removed in. This implementation detail can be ignored by using the appropriate ``PandasDeprecationWarning`` variable, which will be aliased to the proper warning class based on the pandas version. -Not all deprecations have to use ``DeprecationWarning`` but all deprecations should eventually transition to ``FutureWarning``, i.e. deprecations in the last minor release which are planned to be removed in the major release after will immediately use ``FutureWarning``. - -It is recommended to not introduce large-scale deprecations in the last minor release which are planned to be removed in the major release after, since that will immediately be using a loud ``FutureWarning`` with not much time between deprecation and removal. Instead, a ``DeprecationWarning`` should be used, and the removal should be scheduled for a later major release. - ### Enforcement of deprecations When one enforces a deprecation, they should: From 04ecc26eb992c3d30a44e3a8f2f4b3a5a0c00eb8 Mon Sep 17 00:00:00 2001 From: Abdulaziz Aloqeely <52792999+Aloqeely@users.noreply.github.com> Date: Wed, 18 Sep 2024 13:44:15 +0300 Subject: [PATCH 09/10] Update abstract --- .../0017-backwards-compatibility-and-deprecation-policy.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md b/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md index 9c246dd89a63b..99fa48240468d 100644 --- a/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md +++ b/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md @@ -10,6 +10,10 @@ This PDEP defines pandas' backwards compatibility and deprecation policy. +The main additions to [pandas' current version policy](https://pandas.pydata.org/pandas-docs/version/2.2/development/policies.html) are: +- Deprecated functionality should remain unchanged in at least 2 minor releases +- Deprecations should initially use DeprecationWarning, and then be switched to FutureWarning in the last minor release before the major release they are planned to be removed in + ## Motivation Having a clear backwards compatibility and deprecation policy is crucial to having a healthy ecosystem. We want to ensure users can rely on pandas being stable while still allowing the library to evolve. From 472bfb333889e898bc85e2e09515f97a6d3728ee Mon Sep 17 00:00:00 2001 From: Abdulaziz Aloqeely <52792999+Aloqeely@users.noreply.github.com> Date: Wed, 18 Sep 2024 13:46:20 +0300 Subject: [PATCH 10/10] Better wording --- .../0017-backwards-compatibility-and-deprecation-policy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md b/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md index 99fa48240468d..523774740c914 100644 --- a/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md +++ b/web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md @@ -11,7 +11,7 @@ This PDEP defines pandas' backwards compatibility and deprecation policy. The main additions to [pandas' current version policy](https://pandas.pydata.org/pandas-docs/version/2.2/development/policies.html) are: -- Deprecated functionality should remain unchanged in at least 2 minor releases +- Deprecated functionality should remain unchanged in at least 2 minor releases before being changed or removed. - Deprecations should initially use DeprecationWarning, and then be switched to FutureWarning in the last minor release before the major release they are planned to be removed in ## Motivation