backwards-compatibility.rst

Overview

The **backwards-compatibility.rst** file documents the *Backwards Compatibility Policy* of the pytest testing framework. Its primary purpose is to explain pytest's approach to maintaining backward compatibility across releases, managing API transitions, deprecations, removals, and breaking changes. This document serves as a guideline for users, plugin authors, and contributors to understand how pytest evolves without imposing undue disruption.

This file does not contain executable code but provides a detailed policy, historical context, and version support information critical for maintaining ecosystem stability during pytest's evolution.

Key Topics Covered:

Detailed Explanations

Since this is a policy document without code entities such as classes or functions, the documentation focuses on the conceptual frameworks and processes described within.

Backwards Compatibility Transitions

Pytest considers three main types of transitions when evolving APIs:

  1. Trivial transitions

    • APIs that can be translated into newer mechanisms without causing issues.

    • Supported indefinitely.

    • Users encouraged to migrate via documentation.

  2. Transitional transitions

    • Old and new APIs coexist without conflict.

    • Support is maintained with deprecation warnings for an extended period.

    • Removal happens only in major releases, with at least two minor releases of overlap.

    • Deprecated features slated for removal in major version X issue PytestRemovedInXWarning warnings.

    • Upon release of version X, deprecated features become errors by default before actual removal in the next minor release.

  3. True breakage

    • Reserved for changes that are unsustainable to transition or affect very few users.

    • Must be coordinated with the community via detailed issues and proof-of-concept (POC) pull requests.

    • Includes rationale, impact analysis, and migration instructions.

    • Followed by deprecation periods and documentation updates before final removal.

Deprecation and Warning Strategy

History and Philosophy

Python Version Support

Supported Python versions for pytest releases based on active Python maintenance status at release time:

pytest version

Minimum Python version supported

8.4+

3.9+

8.0+

3.8+

7.1+

3.7+

6.2 - 7.0

3.6+

5.0 - 6.1

3.5+

3.3 - 4.6

2.7, 3.4+

This table helps users understand compatibility constraints and plan upgrades accordingly.

Implementation Details and Algorithms

Since this file is a documentation policy (reStructuredText) and not a code module, it contains no implementation code, algorithms, or methods.

However, it references critical implementation mechanisms in pytest's codebase:

Interactions with Other Parts of the System

Visual Diagram

Below is a **flowchart** representing the *Backwards Compatibility Transition Workflow* described in the document. This diagram illustrates the three transition types and their lifecycle from introduction through deprecation to removal.

flowchart TD
    A[Start: New or Modified API] --> B{Type of Transition?}
    B -->|Trivial| C[Support indefinitely]
    B -->|Transitional| D[Support both old & new APIs]
    D --> E[Issue deprecation warning: PytestDeprecationWarning]
    E --> F[Deprecated feature scheduled for removal in major release X]
    F --> G[Use PytestRemovedInXWarning subclass warning]
    G --> H[At release X: warnings become errors by default]
    H --> I[At release X.minor: feature removed]
    B -->|True Breakage| J[Announce in GitHub issue]
    J --> K[Community discussion & impact assessment]
    K --> L[POC Pull Request with deprecation warnings]
    L --> M[Deprecation period & documentation updates]
    M --> N[Merge POC PR for next major release]
    N --> I

    style C fill:#D5F5E3,stroke:#27AE60,stroke-width:2px
    style D fill:#FCF3CF,stroke:#F1C40F,stroke-width:2px
    style J fill:#FADBD8,stroke:#E74C3C,stroke-width:2px

Usage Examples

Because this file is a policy document, direct usage examples are not applicable. However, pytest users and plugin authors can expect the following usage scenarios influenced by this policy:

Summary

The **backwards-compatibility.rst** file is an essential documentation piece that outlines pytest's philosophy and practices for managing backward compatibility. It ensures that users and developers understand how pytest evolves, how deprecations and removals are handled, and how to plan for transitions effectively, minimizing disruption to testing workflows and plugin ecosystems.

By adhering to this policy, pytest balances innovation and progress with stability and user trust over decades of development.

**End of Documentation**