Document resetall, the changelog format and running tests with tox

.pre-commit-config.yaml

@@ -5,7 +5,9 @@ repos:
       - id: rst
         name: rst
         entry: rst-lint
-        files: ^(CHANGELOG.rst|README.rst|HOWTORELEASE.rst|changelog/.*)$
+        files: ^(CHANGELOG|README|RELEASING|docs/.*)\.rst$
+        # index.rst uses Sphinx-only directives (toctree) unknown to docutils.
+        exclude: ^docs/index\.rst$
         language: python
         additional_dependencies: [pygments, restructuredtext_lint]
   - repo: https://github.com/astral-sh/ruff-pre-commit

docs/contributing.rst

@@ -1,4 +1,3 @@
-
 ============
 Contributing
 ============
@@ -15,7 +14,27 @@ Tests are run with ``tox``, you can run the baseline environments before submitt
 
 .. code-block:: console
 
-    $ tox -e py310
+    $ tox -e py314,norewrite
+
+Use ``tox`` rather than running ``pytest`` directly in the virtual env: with the
+editable install, pytest does not rewrite the assertions inside ``pytest_mock``
+itself, so the tests that check assertion introspection fail there regardless
+of your changes.
 
 Style checks and formatting are done automatically during commit courtesy of
 `pre-commit <https://pre-commit.com>`_.
+
+Changelog
+---------
+
+Changes that affect users need an entry in ``CHANGELOG.rst``, under the
+``UNRELEASED`` section at the top. Each entry is a single bullet that starts
+with a link to the PR, and the entries are kept in PR number order, without
+blank lines between them:
+
+.. code-block:: rst
+
+    * `#123 <https://github.com/pytest-dev/pytest-mock/pull/123>`_: Fixed ``mocker.spy`` ...
+
+Open the PR first to get its number, then add the entry. Changes that only
+touch tests or internal tooling don't need an entry.

docs/usage.rst

@@ -25,7 +25,7 @@ The supported methods are:
 * `mocker.patch.dict <https://docs.python.org/3/library/unittest.mock.html#patch-dict>`_
 * `mocker.stopall <https://docs.python.org/3/library/unittest.mock.html#unittest.mock.patch.stopall>`_
 * `mocker.stop <https://docs.python.org/3/library/unittest.mock.html#patch-methods-start-and-stop>`_
-* ``mocker.resetall()``: calls `reset_mock() <https://docs.python.org/3/library/unittest.mock.html#unittest.mock.Mock.reset_mock>`_ in all mocked objects up to this point. With ``side_effect=True``, spies go back to calling the spied code instead of having their ``side_effect`` set to ``None``.
+* ``mocker.resetall()``: calls `reset_mock() <https://docs.python.org/3/library/unittest.mock.html#unittest.mock.Mock.reset_mock>`_ in all mocked objects up to this point. See `Resetting mocks`_ below.
 
 Also, as a convenience, these names from the ``mock`` module are accessible directly from ``mocker``:
 
@@ -171,6 +171,45 @@ callback was awaited. ``await_count`` and the ``assert_awaited*`` methods
 track awaits separately.
 
 
+Resetting mocks
+---------------
+
+``mocker.resetall()`` calls ``reset_mock()`` on the mocks created through
+``mocker`` so far: those from ``mocker.patch`` (and its variants),
+``mocker.spy`` and ``mocker.create_autospec``. Mocks created with
+``mocker.stub()``, ``mocker.async_stub()`` or ``mocker.Mock()`` and the other
+aliases are not tracked, so they are not reset.
+
+.. code-block:: python
+
+    import os
+
+
+    def test_reset(mocker):
+        listdir = mocker.patch("os.listdir", return_value=["foo"])
+        os.listdir("/tmp")
+
+        mocker.resetall()
+        listdir.assert_not_called()
+        assert os.listdir("/tmp") == ["foo"]
+
+        mocker.resetall(return_value=True, side_effect=True)
+        assert os.listdir("/tmp") != ["foo"]
+
+By default only the recorded calls are reset. Pass ``return_value=True`` and/or
+``side_effect=True`` to also reset those, as with ``reset_mock()``.
+
+Some kinds of patches are handled specially:
+
+* ``mocker.patch.multiple``: every mock it patched in is reset, both the ones it
+  created and the ones passed explicitly.
+* ``mocker.patch.dict``: the patched dictionary and its values are left alone.
+* ``mocker.spy``: the ``spy_return``, ``spy_return_iter``, ``spy_return_list``
+  and ``spy_exception`` attributes are set back to their initial values. With
+  ``side_effect=True``, the spy goes back to calling the spied code instead of
+  having its ``side_effect`` set to ``None``, clearing any ``side_effect`` set on
+  the spy.
+
 Usage as context manager
 ------------------------