Warn that warning-capture can break existing suites in the docs and C…

…HANGELOG

Related to discussion in #2430

CHANGELOG.rst

@@ -5,11 +5,25 @@
 New Features
 ------------
 
-* The ``pytest-warnings`` plugin has been integrated into the core, so now ``pytest`` automatically
+* The ``pytest-warnings`` plugin has been integrated into the core and now ``pytest`` automatically
   captures and displays warnings at the end of the test session.
+
+  .. warning::
+
+    This feature may disrupt test suites which apply and treat warnings themselves, and can be
+    disabled in your ``pytest.ini``:
+
+    .. code-block:: ini
+
+      [pytest]
+      addopts = -p no:warnings
+
+    See the `warnings documentation page <https://docs.pytest.org/en/latest/warnings.html>`_ for more
+    information.
+
   Thanks `@nicoddemus`_ for the PR.
 
-* Added ``junit_suite_name`` ini option to specify root `<testsuite>` name for JUnit XML reports (`#533`_).
+* Added ``junit_suite_name`` ini option to specify root ``<testsuite>`` name for JUnit XML reports (`#533`_).
 
 * Added an ini option ``doctest_encoding`` to specify which encoding to use for doctest files.
   Thanks `@wheerd`_ for the PR (`#2101`_).

doc/en/warnings.rst

@@ -5,6 +5,20 @@ Warnings Capture
 
 .. versionadded:: 3.1
 
+.. warning::
+    pytest captures all warnings between tests, which prevents custom warning
+    filters in existing test suites from working. If this causes problems to your test suite,
+    this plugin can be disabled in your ``pytest.ini`` file with:
+
+    .. code-block:: ini
+
+        [pytest]
+        addopts = -p no:warnings
+
+    There's an ongoing discussion about this on `#2430
+    <https://github.com/pytest-dev/pytest/issues/2430>`_.
+
+
 Starting from version ``3.1``, pytest now automatically catches all warnings during test execution
 and displays them at the end of the session::
 

tox.ini

@@ -46,6 +46,8 @@ commands=
 
 
 [testenv:linting]
+skipsdist=True
+usedevelop=True
 basepython = python2.7
 # needed to keep check-manifest working
 setenv =