Skip to content

PDEP-17: Backwards compatibility and deprecation policy #59125

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 12 commits into from
Dec 23, 2024
Merged

PDEP-17: Backwards compatibility and deprecation policy #59125

Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
bbe15b9
PDEP-17: Backwards compatibility and deprecation policy
Aloqeely Jun 27, 2024
2c9657b
Final revision
Aloqeely Jun 27, 2024
a2476e5
resolve contradiction
Aloqeely Jul 5, 2024
58d34e0
Link to public API reference
Aloqeely Jul 5, 2024
7c5be2a
Review
Aloqeely Aug 9, 2024
130d85b
Merge branch 'main' into pdep-17
Aloqeely Aug 9, 2024
607ef54
explain variable
Aloqeely Aug 9, 2024
5493e31
address review
Aloqeely Sep 4, 2024
0a05348
More reviews
Aloqeely Sep 18, 2024
04ecc26
Update abstract
Aloqeely Sep 18, 2024
472bfb3
Better wording
Aloqeely Sep 18, 2024
13330c5
Update status
Aloqeely Dec 22, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 74 additions & 0 deletions web/pandas/pdeps/0017-backwards-compatibility-and-deprecation-policy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
# PDEP-17: Backwards compatibility and deprecation policy

- Created: 27 June 2024
- Status: Accepted
- Discussion: [#59125](https://github.com/pandas-dev/pandas/issues/59125)
- Author: [Abdulaziz Aloqeely](https://github.com/Aloqeely)
- Revision: 1

## Abstract

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 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

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.

## Background

pandas uses a loose variant of semantic versioning.
A pandas release number is written in the format of ``MAJOR.MINOR.PATCH``.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know that MAJOR.MINOR.PATCH is the terminology typically used in semver, but how do people feel about using a terminology like major.feature.bugfix ?

That feels closer to how we also communicate about it (e.g. when announcing it, we didn't call pandas 2.2.0 a "minor" release)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is definitely easier to understand, but don't you think it might be a bit misleading? Because we do release features even in bugfix (patch) releases.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

After digging into past release notes, it seems like v2.2.1 is the only patch release with a new 'feature', so maybe that was just an odd case. I'm OK with this.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I suppose that was an odd case (and it was also only a packaging feature, i.e. a new extra, not an actual code feature)

There might always be exceptions (when there is a good reason), but I think at least the general rule is that bug-fix / patch releases only contain bug fixes (and then even mostly regression fixes)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe worth clarifying that we consider "features" from the perspective of a user and not a developer? The latter can happen at any time

Copy link
Member

@rhshadrach rhshadrach Sep 12, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I find "bugfix" misleading. We typically do not backport mere bugfixes, only those that fix regressions.


## 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.

- Breaking backwards compatibility should benefit more than it harms users.
- 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 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.

## Deprecation process

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.
- Mention how to achieve similar behavior if an alternative is available.
- 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.
- 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 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.

### Enforcement of deprecations

When one enforces a deprecation, they should:
- Add an entry in the release notes.
- For API changes, replace the ``.. deprecated::`` directive in the documentation with a ``.. versionchanged::`` directive.

### PDEP-17 History

- 27 June 2024: Initial version.

[1]: https://pandas.pydata.org/docs/reference/index.html
Loading