Skip to content

cpython-deprecation-workflow.rst

Latest commit

 

History

History
80 lines (57 loc) · 3.04 KB

cpython-deprecation-workflow.rst

File metadata and controls

80 lines (57 loc) · 3.04 KB

Workflow for Deprecating Features in CPython

Deprecation in CPython is a multi-step process that involves notifying users about deprecated functionality, planning its eventual removal, and providing adequate guidance for migration. This document outlines the practical steps required for deprecating a feature, supplementing the policy guidelines defined in PEP 387.

1. Identify Features for Deprecation

Before proposing deprecation:

  • Assess Usage: Use tools like GitHub search, grep, or PyPI statistics to determine the extent and context of usage.
  • Consider Alternatives: Ensure there are suitable replacements or upgrades available.

2. Open an Issue

Start by creating a GitHub issue to propose the deprecation:

  • Clearly describe the feature and why deprecation is needed.
  • Encourage community feedback and suggestions.

3. Deprecation Implementation

Once approved:

  • Raise a Warning: Use :func:`warnings.warn` with :exc:`DeprecationWarning` for typical cases. If the feature is in its early deprecation phase:

    Example:

    import warnings
warnings.warn(
    "Feature X is deprecated and will be removed in Python 3.Y",
    DeprecationWarning,
    stacklevel=2
)

  • Update Documentation:

    • Add a deprecation note in the relevant docstrings.
    • Include details in the "Porting" section of the "What's New" documentation.
    • Update the pending-removal-in-{version}.rst file with the deprecation timeline.

4. Track Deprecations

  • Monitor Usage: After the release, observe community feedback. Deprecations may remain longer than the minimum period if low maintenance overhead is expected or usage is widespread.
  • Timeline Review: Use GitHub milestones or specific deprecation tracking issues to manage timelines.

5. Plan Removal

After the deprecation period (typically 2+ releases):

  • Open a new issue for removal.
  • Follow removal steps:
    • Remove the deprecated code and warnings.
    • Update documentation, removing references to the deprecated feature.
    • Include the removal in the "What's New" for the release.

6. PendingDeprecationWarning Workflow

For gradual deprecations:

  • Use Case: When you want to signal future deprecation but not yet alert end-users.
  • Transition Timeline:
  • Documentation:
    • Mention the pending deprecation in “What’s New.”
    • No pending-removal-in entry is needed during this stage.

7. References and Templates

  • Use .. deprecated:: and .. removed:: Sphinx roles for documentation.
  • Add See Also links to PEP 387 and DevGuide for policy and process details.