Skip to content

Commit

Permalink
Update per Conda Release Schedule changes
Browse files Browse the repository at this point in the history
  • Loading branch information
kenodegard committed Jul 6, 2022
1 parent 4e65fe8 commit 6a13725
Showing 1 changed file with 8 additions and 12 deletions.
20 changes: 8 additions & 12 deletions cep-deprecation.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,16 @@
<table>
<tr><td> Title </td><td> Deprecation Policy </td>
<tr><td> Title </td><td> Conda Deprecation Schedule </td>
<tr><td> Status </td><td> Draft </td></tr>
<tr><td> Author(s) </td><td> Ken Odegard &lt;kodegard@anaconda.com&gt; </td></tr>
<tr><td> Created </td><td> May 20, 2022 </td></tr>
<tr><td> Updated </td><td> May 20, 2022 </td></tr>
<tr><td> Updated </td><td> July 6, 2022 </td></tr>
<tr><td> Discussion </td><td> NA </td></tr>
<tr><td> Implementation </td><td> NA </td></tr>
</table>

## Abstract

Describes a deprecation policy to properly warn about upcoming removals from the codebase. This policy will be applicable to the following:
Describes a deprecation schedule to properly warn about upcoming removals from the codebase. This will be applicable to the following:

- `conda/conda`
- `conda/conda-build`
Expand All @@ -19,23 +19,19 @@ Other [conda](https://github.com/conda) or [conda-incubator](https://github.com/

## Specification

We propose a deprecation policy slower than the release cadence (see CEP-?). This is in acknowledgement of our diverse user groups (e.g. everything from per user per machine installs to multi-user installs on shared clusters).
We propose a deprecation schedule that is slower than the Conda Release Schedule (see CEP-?). This is in acknowledgement of our diverse user groups (e.g. everything from per user per machine installs to multi-user installs on shared clusters).

All deprecations are to be:

1. initially marked as **pending deprecation** (e.g. using Python's `warnings.PendingDeprecationWarning`) and remain in a pending state for at least 3 releases/months
2. at the start of the quarter (i.e. in the X.Y.0 release) all **pending deprecations** that have been pending for 3+ releases/months are marked as **deprecations** (e.g. using Python's `warnings.DeprecationWarning`) and remain in a deprecated state for 3 more releases/months
3. at the start of the following (i.e. in the (X.Y+1).0 release) quarter all **deprecations** that have been deprecated for 3 releases/months are removed
1. initially marked as **pending deprecation** and remain in a pending state for at least three (3+) `MINOR` releases
2. January (`YY.1.0`), May (`YY.5.0`), and September (`YY.9.0`) are deprecation releases where:
- all **pending deprecations** that have been pending for at least three (3+) `MINOR` releases are marked as **deprecations** and remain in a deprecated state for four (4) `MINOR` releases
- all **deprecations** that have been deprecated for four (4) `MINOR` releases are removed

To summarize, features may be marked as **pending deprecation** in any release however **deprecations** and **removals** only occur in the first release of a quarter.

Occasionally there may be code changes that we feel warrant a longer deprecation schedule. If that occurs the deprecation warning will clearly specify that a deviation is occurring and what the expected schedule will be instead.

In an effort to standardize the deprecation messaging we propose the messaging should look something like the following:

- `f"{__name__}.<class/function/constant> is pending deprecation in X.Y.0."`
- `f"{__name__}.<class/function/constant> will be deprecated in (X.Y+1).0."`

## Motivation

Help prevent unexpected breakage of downstream tooling as the codebase evolves.
Expand Down

0 comments on commit 6a13725

Please sign in to comment.