From 0a7fcd135cdefe843c0d7098a237b6b0c1c5da02 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Thu, 3 Dec 2020 22:29:01 +0300 Subject: [PATCH] Docsite: update "Migrating Ansible content to a different collection" info (#72710) * add a reminder about ignore-*.txt entries, fix formatting, add symlink removal note * Update docs/docsite/rst/dev_guide/developing_collections.rst Co-authored-by: Felix Fontein Co-authored-by: David Moreau Simard Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> --- .../rst/dev_guide/developing_collections.rst | 31 +++++++++++++------ 1 file changed, 21 insertions(+), 10 deletions(-) diff --git a/docs/docsite/rst/dev_guide/developing_collections.rst b/docs/docsite/rst/dev_guide/developing_collections.rst index 870723237e6..6bb0306cb01 100644 --- a/docs/docsite/rst/dev_guide/developing_collections.rst +++ b/docs/docsite/rst/dev_guide/developing_collections.rst @@ -538,19 +538,30 @@ First, look at `Ansible Collection Checklist `_: -#. 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 +#. Copy content from the source (old) collection to the target (new) collection. +#. Deprecate the module/plugin with ``removal_version`` scheduled for the next major version in ``meta/runtime.yml`` of the old collection. The deprecation must be released after the copied content has been included in a release of the new collection. +#. When the next major release of the old collection is prepared: + + * remove the module/plugin from the old collection + * remove the symlink stored in ``plugin/modules`` directory if appropriate (mainly when removing from ``community.general`` and ``community.network``) + * remove related unit and integration tests + * remove specific module utils + * remove specific documentation fragments if there are any in the old collection + * add a changelog fragment containing entries for ``removed_features`` and ``breaking_changes``; you can see an example of a changelog fragment in this `pull request `_ + * change ``meta/runtime.yml`` in the old collection: + + * add ``redirect`` to the corresponding module/plugin's entry + * in particular, add ``redirect`` for the removed module utils and documentation fragments if applicable + * remove ``removal_version`` from there + * remove related entries from ``tests/sanity/ignore.txt`` files if exist + * remove changelog fragments for removed content that are not yet part of the changelog (in other words, do not modify `changelogs/changelog.yaml` and do not delete files mentioned in it) + * remove requirements that are no longer required in ``tests/unit/requirements.txt``, ``tests/requirements.yml`` and ``galaxy.yml`` 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. +#. Create a PR against the new collection to copy the content. +#. Deprecate the module/plugin in the old collection. +#. Later create a PR against the old collection to remove the content according to the schedule. Adding the content to the new collection