向後相容性方針

Pytest is an actively evolving project that has been decades in the making. We keep learning about new and better structures to express different details about testing.

While we implement those modifications, we try to ensure an easy transition and don't want to impose unnecessary churn on our users and community/plugin authors.

As of now, pytest considers multiple types of backward compatibility transitions:

  1. trivial: APIs that trivially translate to the new mechanism and do not cause problematic changes.

    We try to support those indefinitely while encouraging users to switch to newer or better mechanisms through documentation.

  2. transitional: the old and new APIs don't conflict, and we can help users transition by using warnings while supporting both for a prolonged period of time.

    We will only start the removal of deprecated functionality in major releases (e.g., if we deprecate something in 3.0, we will start to remove it in 4.0), and keep it around for at least two minor releases (e.g., if we deprecate something in 3.9 and 4.0 is the next release, we start to remove it in 5.0, not in 4.0).

    A deprecated feature scheduled to be removed in major version X will use the warning class PytestRemovedInXWarning (a subclass of PytestDeprecationWarning).

    When the deprecation expires (e.g., 4.0 is released), we won't remove the deprecated functionality immediately but will use the standard warning filters to turn PytestRemovedInXWarning (e.g., PytestRemovedIn4Warning) into errors by default. This approach makes it explicit that removal is imminent and still gives you time to turn the deprecated feature into a warning instead of an error so it can be dealt with in your own time. In the next minor release (e.g., 4.1), the feature will be effectively removed.

  3. True breakage should only be considered when a normal transition is unreasonably unsustainable and would offset important developments or features by years. In addition, they should be limited to APIs where the number of actual users is very small (for example, only impacting some plugins) and can be coordinated with the community in advance.

    Examples for such upcoming changes:

    • removal of pytest_runtest_protocol/nextitem - #895

    • rearranging of the node tree to include FunctionDefinition

    • rearranging of SetupState #895

    True breakages must be announced first in an issue containing:

    • Detailed description of the change

    • Rationale

    • Expected impact on users and plugin authors (example in #895)

    After there's no hard -1 on the issue it should be followed up by an initial proof-of-concept Pull Request.

    This POC serves as both a coordination point to assess impact and potential inspiration to come up with a transitional solution after all.

    After a reasonable amount of time the PR can be merged to base a new major release.

    For the PR to mature from POC to acceptance, it must contain: * Setup of deprecation errors/warnings that help users fix and port their code. If it is possible to introduce a deprecation period under the current series, before the true breakage, it should be introduced in a separate PR and be part of the current release stream. * Detailed description of the rationale and examples on how to port code in doc/en/deprecations.rst.

History

Focus primarily on smooth transition - stance (pre 6.0)

在 pytest 專案中，保持向後相容性具有極高的優先級。雖然多年來我們棄用了一些功能，但其中大部分目前仍受支援。pytest 中所有的棄用措施，都是因為出現了更簡單或更有效率的方法來完成相同的任務，使得舊有的做法變得不再必要。

隨著 pytest 3.0 的發行，我們引進了一套明確的溝通方案，用以說明何時會正式移除舊有的過時功能，並禮貌地請您改用新的替代方案。同時，這也為您留出足夠的時間來調整測試程式碼，或者在有正當理由需要保留已棄用功能時提出疑慮。

To communicate changes, we issue deprecation warnings using a custom warning hierarchy (see Internal pytest warnings). These warnings may be suppressed using the standard means: -W command-line flag or filterwarnings configuration option (see How to capture warnings), but we suggest to use these sparingly and temporarily, and heed the warnings when possible.

We will only start the removal of deprecated functionality in major releases (e.g. if we deprecate something in 3.0, we will start to remove it in 4.0), and keep it around for at least two minor releases (e.g. if we deprecate something in 3.9 and 4.0 is the next release, we start to remove it in 5.0, not in 4.0).

When the deprecation expires (e.g. 4.0 is released), we won't remove the deprecated functionality immediately, but will use the standard warning filters to turn them into errors by default. This approach makes it explicit that removal is imminent, and still gives you time to turn the deprecated feature into a warning instead of an error so it can be dealt with in your own time. In the next minor release (e.g. 4.1), the feature will be effectively removed.

棄用路線圖

Features currently deprecated and removed in previous releases can be found in Deprecations and Removals.

We track future deprecation and removal of features using milestones and the deprecation and removal labels on GitHub.

Python 版本支援

發行的 pytest 版本支援在發行時所有仍處於主動維護狀態的 Python 版本：

pytest 版本

最低 Python 版本

9.0+

3.10+

8.4

3.9+

8.0 - 8.3

3.8+

7.1 - 7.4

3.7+

6.2 - 7.0

3.6+

5.0 - 6.1

3.5+

3.3 - 4.6

2.7, 3.4+

Python 版本的狀態。