From c66cff444c88b1f7b8d3f01cb6fec07fffe3d52e Mon Sep 17 00:00:00 2001
From: Alicia Cozine <879121+acozine@users.noreply.github.com>
Date: Thu, 25 Mar 2021 15:36:46 -0500
Subject: [PATCH] documents the use of ansible.legacy (#73942)

---
 .../docsite/rst/dev_guide/migrating_roles.rst | 23 ++++++++++++++++---
 1 file changed, 20 insertions(+), 3 deletions(-)

diff --git a/docs/docsite/rst/dev_guide/migrating_roles.rst b/docs/docsite/rst/dev_guide/migrating_roles.rst
index d7d8b571157..2ed5f53e848 100644
--- a/docs/docsite/rst/dev_guide/migrating_roles.rst
+++ b/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``.