From 2655fc0c23705d8a0510846dfb6e8af0bf0c5991 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Thu, 24 Sep 2020 21:19:04 +0300 Subject: [PATCH] Docsite: update Migrating Ansible content to a different collection (#71854) Co-authored-by: Felix Fontein --- .../rst/dev_guide/developing_collections.rst | 66 +++++++++---------- 1 file changed, 33 insertions(+), 33 deletions(-) diff --git a/docs/docsite/rst/dev_guide/developing_collections.rst b/docs/docsite/rst/dev_guide/developing_collections.rst index 02f5a4823d8..dd757e55fef 100644 --- a/docs/docsite/rst/dev_guide/developing_collections.rst +++ b/docs/docsite/rst/dev_guide/developing_collections.rst @@ -534,17 +534,41 @@ Migrating Ansible content to a different collection First, look at `Ansible Collection Checklist `_. -To migrate content from one collection to another, you need to create three PRs as follows: +To migrate content from one collection to another, if the collections are parts of `Ansible distribution `_: -#. 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. +#. Copy content from the source (old) collection to the target collection. +#. Deprecate the module/plugin with ``removal_version`` scheduled for the next major version in ``meta/runtime.yml`` of the source collection. The deprecation must be released after the copied content has been included in a release of the target collection. +#. When the next major release comes: + + * remove the module/plugin from the source collection + * add ``redirect`` to the corresponding entry in ``meta/runtime.yml`` + * remove ``removal_version`` from there + +According to the above, you need to create at least three PRs as follows: + +#. Create a PR against the target collection to copy the content. +#. Deprecate the module/plugin in the source collection. +#. Later create a PR against the source collection to remove the content according to the schedule. + + +Adding the content to the new collection +---------------------------------------- + +Create a PR in the new collection to: + +#. Copy ALL the related files 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 ``runtime.yml`` if it exists. +#. Carefully check the moved ``tests/integration`` and ``tests/units`` and update for FQCN. +#. Review ``tests/sanity/ignore-*.txt`` entries in the old collection. +#. Update ``meta/runtime.yml`` in the old collection. 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: +Create a PR against the source collection repository 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. @@ -554,11 +578,6 @@ Create a PR against the old collection repo to remove the modules, module_utils, #. 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. - .. warning:: @@ -568,34 +587,15 @@ Create a PR against the old collection repo to remove the modules, module_utils, #. 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 (in other words, 2.0.0, 3.0.0, and so on). -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: - -#. Update ``lib/ansible/config/ansible_builtin_runtime.yml`` (the redirect entry). -#. Update ``.github/BOTMETA.yml`` (the migrated_to entry) - BOTMETA.yml ----------- -The `BOTMETA.yml `_ in the ansible/ansible GitHub repository is the source of truth for: +The ``BOTMETA.yml``, for example in `community.general collection repository `_, is the source of truth for: * ansibullbot +If the old and/or new collection has ``ansibullbot``, its ``BOTMETA.yml`` must be updated correspondingly. + 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.