documents the use of ansible.legacy (#73942)

docs/docsite/rst/dev_guide/migrating_roles.rst

@@ -110,11 +110,10 @@ This creates the collection directory structure.
 
 5. Update the collection README.md file to add links to any role README.md files.
 
-
 .. _complex_roles_in_collections:
 
-Migrating a role with plugins to a collection
+Migrating a role that contains plugins to a collection
-==============================================
+======================================================
 
 To migrate from a standalone role that has plugins to a collection role:
 
@@ -408,3 +407,21 @@ The following is an example RPM spec file that accomplishes this using this exam
   %doc %{collection_dir}/roles/*/README.md
   %license %{_pkgdocdir}/*/COPYING
   %license %{_pkgdocdir}/*/LICENSE
+
+.. _using_ansible_legacy:
+
+Using ``ansible.legacy`` to access local custom modules from collections-based roles
+=====================================================================================
+
+Some roles use :ref:`local custom modules <developing_locally>` that are not part of the role itself. When you move these roles into collections, they can no longer find those custom plugins. You can add the synthetic collection ``ansible.legacy`` to enable legacy behavior and find those custom plugins. Adding ``ansible.legacy`` configures your role to search the pre-collections default paths for modules and plugins.
+
+To enable a role hosted in a collection to find legacy custom modules and other plugins hosted locally:
+
+Edit the role's ``meta/main.yml`` and add the ``ansible.legacy`` collection to your collection-hosted role to enable the use of legacy custom modules and plugins for all tasks:
+
+.. code-block:: yaml
+
+   collections:
+     - ansible.legacy
+
+Alternatively, you can update the tasks directly by changing ``local_module_name`` to ``ansible.legacy.local_module_name``.