Merge pull request #3983 from nicoddemus/update-backward-policy

Review backward compatibility policy

.gitignore

@@ -24,6 +24,7 @@ src/_pytest/_version.py
 .eggs/
 
 doc/*/_build
+doc/*/.doctrees
 build/
 dist/
 *.egg-info

doc/en/backwards-compatibility.rst

@@ -7,14 +7,14 @@ Keeping backwards compatibility has a very high priority in the pytest project.
 
 With the pytest 3.0 release we introduced a clear communication scheme for when we will actually remove the old busted joint and politely ask you to use the new hotness instead, while giving you enough time to adjust your tests or raise concerns if there are valid reasons to keep deprecated functionality around.
 
-To communicate changes we are already issuing deprecation warnings, but they are not displayed by default. In pytest 3.0 we changed the default setting so that pytest deprecation warnings are displayed if not explicitly silenced (with ``--disable-pytest-warnings``).
+To communicate changes we issue deprecation warnings using a custom warning hierarchy (see :ref:`internal-warnings`). These warnings may be suppressed using the standard means: ``-W`` command-line flag or ``filterwarnings`` ini options (see :ref:`warnings`), but we suggest to use these sparingly and temporarily, and heed the warnings when possible.
 
-We will only remove deprecated functionality in major releases (e.g. if we deprecate something in 3.0 we will 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 will not remove it in 4.0 but in 5.0).
+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.
 
 
 Deprecation Roadmap
 -------------------
 
 We track deprecation and removal of features using milestones and the `deprecation <https://github.com/pytest-dev/pytest/issues?q=label%3A%22type%3A+deprecation%22>`_ and `removal <https://github.com/pytest-dev/pytest/labels/type%3A%20removal>`_ labels on GitHub.
-
-Following our deprecation policy, after starting issuing deprecation warnings we keep features for *at least* two minor versions before considering removal.

doc/en/warnings.rst

@@ -330,6 +330,9 @@ You can also use it as a contextmanager::
             myobject.deprecated_method()
 
 
+
+.. _internal-warnings:
+
 Internal pytest warnings
 ------------------------
 
@@ -363,9 +366,8 @@ defines an ``__init__`` constructor, as this prevents the class from being insta
 
 These warnings might be filtered using the same builtin mechanisms used to filter other types of warnings.
 
-Following our :ref:`backwards-compatibility`, deprecated features will be kept *at least* two minor releases. After that,
-they will changed so they by default raise errors instead of just warnings, so users can adapt to it on their own time
-if not having done so until now. In a later release the deprecated feature will be removed completely.
+Please read our :ref:`backwards-compatibility` to learn how we proceed about deprecating and eventually removing
+features.
 
 The following warning types ares used by pytest and are part of the public API: