From 212fcd903aeb685a3b39875be82fc84ff58ebc56 Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <bruno@soliv.dev>
Date: Sat, 17 Oct 2026 12:25:06 -0300
Subject: [PATCH] Document resetall, the changelog format and running tests
 with tox

* usage: add a "Resetting mocks" section describing what resetall()
  resets, its return_value/side_effect arguments, and how patch.multiple,
  patch.dict and spies are handled.
* contributing: explain why tests should be run with tox, update the
  baseline environments, and describe the changelog entry format.
* pre-commit: lint RELEASING.rst and the docs with the rst hook, which
  still referred to HOWTORELEASE.rst and a changelog/ directory.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .pre-commit-config.yaml |  4 +++-
 docs/contributing.rst   | 23 +++++++++++++++++++++--
 docs/usage.rst          | 41 ++++++++++++++++++++++++++++++++++++++++-
 3 files changed, 64 insertions(+), 4 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index f9de80d..0086f9c 100644
--- a/.pre-commit-config.yaml
+++ b/.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
diff --git a/docs/contributing.rst b/docs/contributing.rst
index 0830f23..9c64420 100644
--- a/docs/contributing.rst
+++ b/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.
diff --git a/docs/usage.rst b/docs/usage.rst
index 16f4e6c..d8ca38f 100644
--- a/docs/usage.rst
+++ b/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
 ------------------------