You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md
+2-7Lines changed: 2 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -30,10 +30,10 @@ A pandas release number is written in the format of ``MAJOR.MINOR.PATCH``.
30
30
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.
31
31
32
32
- Breaking backwards compatibility should benefit more than it harms users.
33
-
- Breaking changes should go through a deprecation cycle before being implemented.
33
+
- Breaking changes should go through a deprecation cycle before being implemented if possible.
34
34
- Breaking changes should only occur in major releases.
35
35
- No deprecations should be introduced in patch releases.
36
-
- Deprecated functionality should remain unchanged for at least 6 months before being changed or removed.
36
+
- Deprecated functionality should remain unchanged in at least 2 minor releases before being changed or removed.
37
37
38
38
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.
39
39
@@ -44,7 +44,6 @@ Deprecation provides a way to warn developers and give them time to adapt their
44
44
A deprecation's warning message should:
45
45
- Provide information on what is changing.
46
46
- Mention how to achieve similar behavior if an alternative is available.
47
-
- Include the version in which the deprecation will be enforced.
48
47
- For large-scale deprecations, it is recommended to include a reason for the deprecation, alongside a discussion link to get user feedback.
49
48
50
49
Additionally, when one introduces a deprecation, they should:
@@ -58,10 +57,6 @@ Additionally, when one introduces a deprecation, they should:
58
57
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.
59
58
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.
60
59
61
-
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``.
62
-
63
-
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.
0 commit comments