Skip to content

PEP 387: Add Soft Deprecation section #3182

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 4 commits into from
Jul 3, 2023
Merged

PEP 387: Add Soft Deprecation section #3182

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
53dab72
PEP 387: Add Soft Deprecation section
vstinner Jun 26, 2023
e8899f4
Add link to the discussion
vstinner Jun 30, 2023
5ab7828
Fix PEP format
vstinner Jun 30, 2023
f772f8d
Add myself to PEP 387 CODEOWNERS
vstinner Jun 30, 2023
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
2 changes: 1 addition & 1 deletion .github/CODEOWNERS
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -241,7 +241,7 @@ pep-0378.txt @rhettinger
# pep-0384.txt
pep-0385.txt @pitrou @birkenfeld
# pep-0386.txt
pep-0387.txt @benjaminp
pep-0387.txt @benjaminp @vstinner
# pep-0389.txt
# pep-0390.txt
pep-0391.txt @vsajip
Expand Down
29 changes: 27 additions & 2 deletions pep-0387.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,13 @@ Version: $Revision$
Last-Modified: $Date$
Author: Benjamin Peterson <[email protected]>
PEP-Delegate: Brett Cannon <[email protected]>
Discussions-To: https://discuss.python.org/t/pep-387-backwards-compatibilty-policy/4421
Status: Active
Type: Process
Content-Type: text/x-rst
Created: 18-Jun-2009
Post-History: 19-Jun-2009, 12-Jun-2020
Post-History: `19-Jun-2009 <https://mail.python.org/archives/list/[email protected]/thread/YAZQHFUCYEYIX5MIG6LFJLCVQ5ORVUM6/>`__,
`12-Jun-2020 <https://discuss.python.org/t/pep-387-backwards-compatibilty-policy/4421>`__,
`16-Jun-2023 <https://discuss.python.org/t/formalize-the-concept-of-soft-deprecation-dont-schedule-removal-in-pep-387-backwards-compatibility-policy/27957>`__


Abstract
Expand Down Expand Up @@ -114,6 +115,30 @@ Basic policy for backwards compatibility
platforms).


Soft Deprecation
================

A soft deprecation can be used when using an API which should no longer
be used to write new code, but it remains safe to continue using it in
existing code. The API remains documented and tested, but will not be
developed further (no enhancement).

The main difference between a "soft" and a (regular) "hard" deprecation
is that the soft deprecation does not imply scheduling the removal of
the deprecated API.

Another difference is that a soft deprecation does not issue a warning:
it's only mentioned in the documentation, whereas usually a "hard"
deprecation issues a ``DeprecationWarning`` warning at runtime. The
documentation of a soft deprecation should explain why the API should be
avoided, and if possible propose a replacement.

If the decision is made to deprecate (in the regular sense) a feature
that is currently soft deprecated, the deprecation must follow the
`Backwards Compatibility Rules`_ (i.e., there is no exception because
the feature is already soft deprecated).


Making Incompatible Changes
===========================

Expand Down