document how to migrate between collections (ansible#70243)

* document how to migrate between collections
* Apply suggestions from code review

Co-authored-by: John R Barker <john@johnrbarker.com>
Co-authored-by: Felix Fontein <felix@fontein.de>

docs/docsite/rst/dev_guide/developing_collections.rst

@@ -469,24 +469,70 @@ Collection versions use `Semantic Versioning <https://semver.org/>`_ for version
 
 .. _migrate_to_collection:
 
-Migrating Ansible content to a collection
-=========================================
+Migrating Ansible content to a different collection
+====================================================
+
+To migrate content from one collection to another, you need to create three PRs as follows:
+
+#. Create a PR against the old collection to remove the content.
+#. Create a PR against the new collection to add the files removed in step 1.
+#. Update the ``ansible/ansible:devel`` branch entries for all files moved.
+
+
+Removing the content from the old collection
+----------------------------------------------
+
+Create a PR against the old collection repo to remove the modules, module_utils, plugins, and docs_fragments related to this migration:
+
+#. If you are removing an action plugin, remove the corresponding module that contains the documentation.
+#. If you are removing a module, remove any corresponding action plugin that should stay with it.
+#. Remove any entries about removed plugins from ``meta/runtime.yml``. Ensure they are added into the new repo.
+#. Remove sanity ignore lines from ``tests/sanity/ignore\*.txt``
+#. Remove associated integration tests from ``tests/integrations/targets/`` and unit tests from ``tests/units/plugins/``.
+#. if you are removing from content from ``community.general`` or ``community.network``, remove entries from ``.github/BOTMETA.yml``.
+#. Carefully review ``meta/runtime.yml`` for any entries you may need to remove or update, in particular deprecated entries.
+#. Update ``meta/runtime.yml`` to contain redirects for EVERY PLUGIN, pointing to the new collection name.
+#. If possible, do not yet add deprecation warnings to the new ``meta/runtime.yml`` entries, but only for a later major release. So the order should be:
+    1. Remove content, add redirects in 3.0.0;
+    2. Deprecate redirects in 4.0.0;
+    3. Set removal version to 5.0.0 or later.
 
-You can experiment with migrating existing modules into a collection using the `content_collector tool <https://github.com/ansible/content_collector>`_. The ``content_collector`` is a playbook that helps you migrate content from an Ansible distribution into a collection.
 
 .. warning::
 
-	This tool is in active development and is provided only for experimentation and feedback at this point.
+	Maintainers for the old collection have to make sure that the PR is merged in a way that it does not break user experience and semantic versioning:
+
+	#. A new version containing the merged PR must not be released before the collection the content has been moved to has been released again, with that content contained in it. Otherwise the redirects cannot work and users relying on that content will experience breakage.
+	#. Once 1.0.0 of the collection from which the content has been removed has been released, such PRs can only be merged for a new **major** version (i.e. 2.0.0, 3.0.0, etc.).
+
+
+Adding the content to the new collection
+-----------------------------------------
+
+Create a PR in the new collection to:
+
+#. Add ALL the files removed in first PR (from the old collection).
+#. If it is an action plugin, include the corresponding module with documentation.
+#. If it is a module, check if it has a corresponding action plugin that should move with it.
+#. Check ``meta/ `` for relevant updates to ``action_groups.yml`` and ``runtime.yml`` if they exist.
+#. Carefully check the moved ``tests/integration`` and ``tests/units`` and update for FQCN.
+#. Review ``tests/sanity/ignore-\*.txt`` entries.
+#. Update ``meta/runtime.yml``.
+
+Updating ``ansible/ansible:devel`` branch entries for all files moved
+----------------------------------------------------------------------
+
+Create a third PR on ``ansible/ansible`` repository to:
 
-See the `content_collector README <https://github.com/ansible/content_collector>`_ for full details and usage guidelines.
+#. Update ``lib/ansible/config/ansible_builtin_runtime.yml`` (the redirect entry).
+#. Update ``.github/BOTMETA.yml`` (the migrated_to entry)
 
 BOTMETA.yml
 -----------
 
 The `BOTMETA.yml <https://github.com/ansible/ansible/blob/devel/.github/BOTMETA.yml>`_ in the ansible/ansible GitHub repository is the source of truth for:
 
 * ansibullbot
-* the docs build for collections-based modules
 
 Ansibulbot will know how to redirect existing issues and PRs to the new repo.
 The build process for docs.ansible.com will know where to find the module docs.