Skip to content

Commit 8923875

Browse files
authored
[Docs] Add note about setuptools not defining the introduction of warnings as a breaking change (#5025)
2 parents 3894bb9 + 2e3c6a8 commit 8923875

File tree

1 file changed

+10
-0
lines changed

1 file changed

+10
-0
lines changed

docs/userguide/interfaces.rst

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,16 @@ reserve the right of speeding up the deprecation cycle and shortening deprecatio
5050
Note that these are exceptional circumstances and that the project will
5151
carefully attempt to find alternatives before resorting to unscheduled removals.
5252

53+
.. important::
54+
In the context of ``setuptools``, the introduction of :py:mod:`warnings`
55+
(including deprecation warnings) is not considered a breaking change *per se*.
56+
Instead it is considered a backwards compatible *communication action* that
57+
precedes an upcoming breaking change. This is becauset code
58+
containing warnings typically does not fail and can successfully terminate
59+
execution, unless users explicitly opt into transforming those warnings
60+
into errors (e.g., via Python's :external+python:ref:`-W option or
61+
PYTHONWARNINGS environment variable <using-on-warnings>`).
62+
5363

5464
What to do when deprecation periods are undefined?
5565
--------------------------------------------------

0 commit comments

Comments
 (0)