docs: Add migration guides for pytest-asyncio v0.21 and v0.23.

docs/how-to-guides/index.rst

@@ -5,6 +5,8 @@ How-To Guides
 .. toctree::
   :hidden:
 
+  migrate_from_0_21
+  migrate_from_0_23
   change_fixture_loop
   change_default_fixture_loop
   run_class_tests_in_same_loop

docs/how-to-guides/migrate_from_0_21.rst

@@ -0,0 +1,17 @@
+.. _how_to_guides/migrate_from_0_21:
+
+========================================
+How to migrate from pytest-asyncio v0.21
+========================================
+1. If your test suite re-implements the *event_loop* fixture, make sure the fixture implementations don't do anything besides creating a new asyncio event loop, yielding it, and closing it.
+2. Convert all synchronous test cases requesting the *event_loop* fixture to asynchronous test cases.
+3. Convert all synchronous fixtures requesting the *event_loop* fixture to asynchronous fixtures.
+4. Remove the *event_loop* argument from all asynchronous test cases in favor of ``event_loop = asyncio.get_running_loop()``.
+5. Remove the *event_loop* argument from all asynchronous fixtures in favor of ``event_loop = asyncio.get_running_loop()``.
+
+Go through all re-implemented *event_loop* fixtures in your test suite one by one, starting with the the fixture with the deepest nesting level and take note of the fixture scope:
+
+1. For all tests and fixtures affected by the re-implemented *event_loop* fixture, configure the *loop_scope* for async tests and fixtures to match the *event_loop* fixture scope. This can be done for each test and fixture individually using either the ``pytest.mark.asyncio(loop_scope="…")`` marker for async tests or ``@pytest_asyncio.fixture(loop_scope="…")`` for async fixtures. Alternatively, you can set the default loop scope for fixtures using the :ref:`asyncio_default_fixture_loop_scope <configuration/asyncio_default_fixture_loop_scope>` configuration option. Snippets to mark all tests with the same *asyncio* marker, thus sharing the same loop scope, are present in the how-to section of the documentation. Depending on the homogeneity of your test suite, you may want a mixture of explicit decorators and default settings.
+2. Remove the re-implemented *event_loop* fixture.
+
+If you haven't set the *asyncio_default_fixture_loop_scope* configuration option, yet, set it to *function* to silence the deprecation warning.

docs/how-to-guides/migrate_from_0_23.rst

@@ -0,0 +1,8 @@
+========================================
+How to migrate from pytest-asyncio v0.23
+========================================
+The following steps assume that your test suite has no re-implementations of the *event_loop* fixture, nor explicit fixtures requests for it. If this isn't the case, please follow the :ref:`migration guide for pytest-asyncio v0.21. <how_to_guides/migrate_from_0_21>`
+
+1. Explicitly set the *loop_scope* of async fixtures by replacing occurrences of ``@pytest.fixture(scope="…")`` and ``@pytest_asyncio.fixture(scope="…")`` with ``@pytest_asyncio.fixture(loop_scope="…", scope="…")`` such that *loop_scope* and *scope* are the same. If you use auto mode, resolve all import errors from missing imports of *pytest_asyncio*. If your async fixtures all use the same *loop_scope*, you may choose to set the *asyncio_default_fixture_loop_scope* configuration option to that loop scope, instead.
+2. If you haven't set *asyncio_default_fixture_loop_scope*, set it to *function* to address the deprecation warning about the unset configuration option.
+3. Change all occurrences of ``pytest.mark.asyncio(scope="…")`` to ``pytest.mark.asyncio(loop_scope="…")`` to address the deprecation warning about the *scope* argument to the *asyncio* marker.