From 2ff398acf76269794ca8fe61669b4898b337140d Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Wed, 23 Mar 2022 20:39:07 +0100 Subject: [PATCH 01/17] Describe how collections can be removed from the Ansible package. --- removal_from_ansible.rst | 47 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 removal_from_ansible.rst diff --git a/removal_from_ansible.rst b/removal_from_ansible.rst new file mode 100644 index 0000000..10c32de --- /dev/null +++ b/removal_from_ansible.rst @@ -0,0 +1,47 @@ +***************************************************** +Ansible Community Package Collections Removal Process +***************************************************** + +.. contents:: Topics + +Overview +======== + +This document describes under which circumstances collections can be removed from the `Ansible community package `_ (`build data `_). Right now this document tries to set up some first processes. In cases of emergency the `Ansible Community Engineering Steering Committee `_ can vote on emergency exceptions, but the goal is to only use processes documented in here. + +Removing broken collections +=========================== + +If it turns out that a collection contained in Ansible X.0.0 depends on another collection included in X.0.0 and does not work with it, the collection can be removed from Ansible (X+1).0.0 under the following conditions: + +1. The collection seems to be unmaintained, and nobody successfully manages to fix the problems. +2. The imminent removal in the next major Ansible release is announced in the Ansible changelog, in The Bullhorn, and in the collection's issue tracker at least two months before the (X+1).0.0 release, and at least one month before the first (X+1).0.0 beta release. + +Conditions under which the collection can stay in the Ansible package before removal in Ansible X+1: + +1. The issues have to be fixed and a new release (bugfix, minor or major) has to be made before the Ansible X+1 feature freeze. Also someone has to promise to maintain the collection and prevent a similar situation at least for some time. + +Conditions under which the collections can be re-included in the Ansible package without going through the full inclusion process (https://github.com/ansible-collections/ansible-inclusion/): + +1. The issues have to be fixed and a new release has to be made before the Ansible X+2 feature freeze. Also someone has to promise to maintain the collection and prevent a similar situation at least for some time. + +Removing unmaintained collections +================================= + +A collection is considered unmaintained if multiple of the following conditions are satisfied: + +1. There has been no activity in the collection repository for several months. +2. CI has stopped passing (or even has not been running) for several months. +3. Bug reports and bugfix PRs start piling up without being reviewed or merged. + +There is no complete formal definition of what it means that a collection is considered unmaintained. To start the process of removing an unmaintained collection, the following has to be done in the following order: + +1. The appearance that the collection is no longer maintained and might be removed from the Ansible package has to be announced both in The Bullhorn and in the collection's issue tracker. +2. The Ansible Community Engineering Steering Committee (SC) has to look at the collection and vote that it considers it unmaintained. This must happen at least four weeks after the notice has appeared in the collection's issue tracker and in The Bullhorn, and the vote must be open for at least one week. +3. If the SC votes that the collection seems to unmaintained, another announcement is made in the collection's issue tracker, in The Bullhorn, and in the Ansible changelog that it will be removed from Ansible Y release. Here Y must be X+1 if Ansible X.0.0 will be released next, or Y must be X+1 if Ansible X.0.0 has already been released. This means that the announcement of impending removal will be active for at least one major release cycle of Ansible. + +Conditions under which the collection can stay in the Ansible package before removal in Ansible X+1: + +1. One or multiple maintainers step up, or return, to clean up the collection's state. The Steering Committee will vote on whether the result is acceptable. A negative vote must come with a good explanation why the clean up work has not been sufficient. + +Once the collection has been removed from Ansible Y.0.0, it needs to go through the full inclusion process to be re-added to the Ansible package. Exceptions are only possible if the Steering Committee votes on them, and it is in the discretion of the Steering Committee to deny a fast re-entry without going through the full review process. From 943a61acfe78a0f5fb8ee8d940ba622713031da6 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Fri, 25 Mar 2022 07:40:56 +0100 Subject: [PATCH 02/17] Apply suggestions from code review Co-authored-by: Andrew Klychkov --- removal_from_ansible.rst | 34 ++++++++++++++++++++-------------- 1 file changed, 20 insertions(+), 14 deletions(-) diff --git a/removal_from_ansible.rst b/removal_from_ansible.rst index 10c32de..9ee2bcf 100644 --- a/removal_from_ansible.rst +++ b/removal_from_ansible.rst @@ -7,32 +7,36 @@ Ansible Community Package Collections Removal Process Overview ======== -This document describes under which circumstances collections can be removed from the `Ansible community package `_ (`build data `_). Right now this document tries to set up some first processes. In cases of emergency the `Ansible Community Engineering Steering Committee `_ can vote on emergency exceptions, but the goal is to only use processes documented in here. +This document describes under which circumstances collections can be removed from the `Ansible community package `_ (`build data `_). -Removing broken collections -=========================== +Right now this document tries to set up some first processes. In cases of emergency the `Ansible Community Engineering Steering Committee `_ can vote on emergency exceptions, but the goal is to only use processes documented in here. + +Broken collections +================== If it turns out that a collection contained in Ansible X.0.0 depends on another collection included in X.0.0 and does not work with it, the collection can be removed from Ansible (X+1).0.0 under the following conditions: -1. The collection seems to be unmaintained, and nobody successfully manages to fix the problems. -2. The imminent removal in the next major Ansible release is announced in the Ansible changelog, in The Bullhorn, and in the collection's issue tracker at least two months before the (X+1).0.0 release, and at least one month before the first (X+1).0.0 beta release. +1. The collection seems to be unmaintained and nobody successfully manages to fix the problems. +2. The imminent removal in the next major Ansible release and its reasons are announced in the Ansible changelog, in The Bullhorn, and in the collection's issue tracker at least two months before the (X+1).0.0 release, and at least one month before the first (X+1).0.0 beta release. The announcement must also contain information that, to prevent the removal, the collection urgently needs new maintainers who can fix the problems. Conditions under which the collection can stay in the Ansible package before removal in Ansible X+1: -1. The issues have to be fixed and a new release (bugfix, minor or major) has to be made before the Ansible X+1 feature freeze. Also someone has to promise to maintain the collection and prevent a similar situation at least for some time. +#. The issues have to be fixed and a new release (bugfix, minor or major) has to be made before the Ansible X+1 feature freeze. +#. Someone has to promise to maintain the collection and prevent a similar situation at least for some time. -Conditions under which the collections can be re-included in the Ansible package without going through the full inclusion process (https://github.com/ansible-collections/ansible-inclusion/): +Conditions under which the collections can be re-included in the Ansible package without going through the `full inclusion process `_: -1. The issues have to be fixed and a new release has to be made before the Ansible X+2 feature freeze. Also someone has to promise to maintain the collection and prevent a similar situation at least for some time. +#. The issues have to be fixed and a new release has to be made before the Ansible X+2 feature freeze. +#. Someone has to promise to maintain the collection and prevent a similar situation at least for some time. -Removing unmaintained collections -================================= +Unmaintained collections +======================== A collection is considered unmaintained if multiple of the following conditions are satisfied: -1. There has been no activity in the collection repository for several months. -2. CI has stopped passing (or even has not been running) for several months. -3. Bug reports and bugfix PRs start piling up without being reviewed or merged. +#. There has been no maintainer's activity in the collection repository for several months (for example, pull request merges and releases). +#. CI has stopped passing (or even has not been running) for several months. +#. Bug reports and bugfix PRs start piling up without being reviewed. There is no complete formal definition of what it means that a collection is considered unmaintained. To start the process of removing an unmaintained collection, the following has to be done in the following order: @@ -42,6 +46,8 @@ There is no complete formal definition of what it means that a collection is con Conditions under which the collection can stay in the Ansible package before removal in Ansible X+1: -1. One or multiple maintainers step up, or return, to clean up the collection's state. The Steering Committee will vote on whether the result is acceptable. A negative vote must come with a good explanation why the clean up work has not been sufficient. +#. One or multiple maintainers step up, or return, to clean up the collection's state. +#. There have been concrete results made by new maintainers (for example, CI has been fixed, the collection has been released, pull request authors have got meaningful feedback). +#. The Steering Committee votes on whether the result is acceptable. A negative vote must come with a good explanation why the clean up work has not been sufficient. Once the collection has been removed from Ansible Y.0.0, it needs to go through the full inclusion process to be re-added to the Ansible package. Exceptions are only possible if the Steering Committee votes on them, and it is in the discretion of the Steering Committee to deny a fast re-entry without going through the full review process. From a2a5b4935d824e81b87777f10c5017be2ec29e12 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Fri, 25 Mar 2022 07:41:59 +0100 Subject: [PATCH 03/17] More updates. --- removal_from_ansible.rst | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/removal_from_ansible.rst b/removal_from_ansible.rst index 9ee2bcf..36881e0 100644 --- a/removal_from_ansible.rst +++ b/removal_from_ansible.rst @@ -14,10 +14,14 @@ Right now this document tries to set up some first processes. In cases of emerge Broken collections ================== -If it turns out that a collection contained in Ansible X.0.0 depends on another collection included in X.0.0 and does not work with it, the collection can be removed from Ansible (X+1).0.0 under the following conditions: +A collection is considered broken if one of the following conditions is true: -1. The collection seems to be unmaintained and nobody successfully manages to fix the problems. -2. The imminent removal in the next major Ansible release and its reasons are announced in the Ansible changelog, in The Bullhorn, and in the collection's issue tracker at least two months before the (X+1).0.0 release, and at least one month before the first (X+1).0.0 beta release. The announcement must also contain information that, to prevent the removal, the collection urgently needs new maintainers who can fix the problems. +#. It depends on another collection included in X.0.0 but does not work with the actual version of it that is included, and there is no content in the collection that still works. + +If the collection is broken, it can be removed from Ansible (X+1).0.0 under the following conditions: + +#. The collection seems to be unmaintained and nobody successfully manages to fix the problems. +#. The imminent removal in the next major Ansible release and its reasons are announced in the Ansible changelog, in The Bullhorn, and in the collection's issue tracker at least two months before the (X+1).0.0 release, and at least one month before the first (X+1).0.0 beta release. The announcement must also contain information that, to prevent the removal, the collection urgently needs new maintainers who can fix the problems. Conditions under which the collection can stay in the Ansible package before removal in Ansible X+1: @@ -40,9 +44,9 @@ A collection is considered unmaintained if multiple of the following conditions There is no complete formal definition of what it means that a collection is considered unmaintained. To start the process of removing an unmaintained collection, the following has to be done in the following order: -1. The appearance that the collection is no longer maintained and might be removed from the Ansible package has to be announced both in The Bullhorn and in the collection's issue tracker. -2. The Ansible Community Engineering Steering Committee (SC) has to look at the collection and vote that it considers it unmaintained. This must happen at least four weeks after the notice has appeared in the collection's issue tracker and in The Bullhorn, and the vote must be open for at least one week. -3. If the SC votes that the collection seems to unmaintained, another announcement is made in the collection's issue tracker, in The Bullhorn, and in the Ansible changelog that it will be removed from Ansible Y release. Here Y must be X+1 if Ansible X.0.0 will be released next, or Y must be X+1 if Ansible X.0.0 has already been released. This means that the announcement of impending removal will be active for at least one major release cycle of Ansible. +#. The appearance that the collection is no longer maintained and might be removed from the Ansible package has to be announced both in The Bullhorn and in the collection's issue tracker. +#. The Ansible Community Engineering Steering Committee (SC) has to look at the collection and vote that it considers it unmaintained. This must happen at least four weeks after the notice has appeared in the collection's issue tracker and in The Bullhorn, and the vote must be open for at least one week. +#. If the SC votes that the collection seems to unmaintained, another announcement is made in the collection's issue tracker, in The Bullhorn, and in the Ansible changelog that it will be removed from Ansible Y release. Here Y must be X+1 if Ansible X.0.0 will be released next, or Y must be X+2 if Ansible X.0.0 has already been released. This means that the announcement of impending removal will be active for at least one major release cycle of Ansible. Conditions under which the collection can stay in the Ansible package before removal in Ansible X+1: From fd4716284115cbc418cf111b49564fd732c40771 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Wed, 6 Apr 2022 21:54:03 +0200 Subject: [PATCH 04/17] Apply suggestions from code review Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> --- removal_from_ansible.rst | 29 ++++++++++++++++++----------- 1 file changed, 18 insertions(+), 11 deletions(-) diff --git a/removal_from_ansible.rst b/removal_from_ansible.rst index 36881e0..8b6db67 100644 --- a/removal_from_ansible.rst +++ b/removal_from_ansible.rst @@ -7,21 +7,28 @@ Ansible Community Package Collections Removal Process Overview ======== -This document describes under which circumstances collections can be removed from the `Ansible community package `_ (`build data `_). +Sometimes the Ansible community removes a collection from the Ansible package. We try to do this only rarely. This document describes why we might remove a collection from the `Ansible community package `_ (`build data `_). -Right now this document tries to set up some first processes. In cases of emergency the `Ansible Community Engineering Steering Committee `_ can vote on emergency exceptions, but the goal is to only use processes documented in here. +In cases of emergency (for example, a serious security vulnerability that is not fixed in a collection) the `Ansible Community Engineering Steering Committee `_ can vote on emergency exceptions. In most cases, we follow the rules listed on this page. -Broken collections -================== +Reasons to remove a collection +============================== -A collection is considered broken if one of the following conditions is true: + +Collection is broken +-------------------- + +The community can remove a collection from the Ansible community package if the collection is broken. A collection is considered broken if one of the following conditions is true: #. It depends on another collection included in X.0.0 but does not work with the actual version of it that is included, and there is no content in the collection that still works. If the collection is broken, it can be removed from Ansible (X+1).0.0 under the following conditions: -#. The collection seems to be unmaintained and nobody successfully manages to fix the problems. -#. The imminent removal in the next major Ansible release and its reasons are announced in the Ansible changelog, in The Bullhorn, and in the collection's issue tracker at least two months before the (X+1).0.0 release, and at least one month before the first (X+1).0.0 beta release. The announcement must also contain information that, to prevent the removal, the collection urgently needs new maintainers who can fix the problems. +#. The collection seems to be unmaintained and nobody fixes the problems. +#. The plan to remove the collection in the next major Ansible release is publicized at least two months before the (X+1).0.0 release, and at least one month before the first (X+1).0.0 beta release. The removal must be announced in multiple places: +- included in the Ansible changelog +- announced in The Bullhorn +The announcement must state the reasons for the proposed removal and alert maintainers and the Ansible community that, to prevent the removal, the collection urgently needs new maintainers who can fix the problems. Conditions under which the collection can stay in the Ansible package before removal in Ansible X+1: @@ -33,8 +40,8 @@ Conditions under which the collections can be re-included in the Ansible package #. The issues have to be fixed and a new release has to be made before the Ansible X+2 feature freeze. #. Someone has to promise to maintain the collection and prevent a similar situation at least for some time. -Unmaintained collections -======================== +Collection is unmaintained +-------------------------- A collection is considered unmaintained if multiple of the following conditions are satisfied: @@ -42,10 +49,10 @@ A collection is considered unmaintained if multiple of the following conditions #. CI has stopped passing (or even has not been running) for several months. #. Bug reports and bugfix PRs start piling up without being reviewed. -There is no complete formal definition of what it means that a collection is considered unmaintained. To start the process of removing an unmaintained collection, the following has to be done in the following order: +There is no complete formal definition of an unmaintained collection. To start the process of removing an unmaintained collection, the following must be done in the following order: #. The appearance that the collection is no longer maintained and might be removed from the Ansible package has to be announced both in The Bullhorn and in the collection's issue tracker. -#. The Ansible Community Engineering Steering Committee (SC) has to look at the collection and vote that it considers it unmaintained. This must happen at least four weeks after the notice has appeared in the collection's issue tracker and in The Bullhorn, and the vote must be open for at least one week. +#. The Ansible Community Engineering Steering Committee (SC) must look at the collection and vote that it considers it unmaintained. This must happen at least four weeks after the notice has appeared in the collection's issue tracker and in The Bullhorn, and the vote must be open for at least one week. #. If the SC votes that the collection seems to unmaintained, another announcement is made in the collection's issue tracker, in The Bullhorn, and in the Ansible changelog that it will be removed from Ansible Y release. Here Y must be X+1 if Ansible X.0.0 will be released next, or Y must be X+2 if Ansible X.0.0 has already been released. This means that the announcement of impending removal will be active for at least one major release cycle of Ansible. Conditions under which the collection can stay in the Ansible package before removal in Ansible X+1: From a7daa800f773e1e894879fb431076f4014f40041 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Wed, 6 Apr 2022 21:55:10 +0200 Subject: [PATCH 05/17] Apply suggestions from code review Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> --- removal_from_ansible.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/removal_from_ansible.rst b/removal_from_ansible.rst index 8b6db67..4f5eda7 100644 --- a/removal_from_ansible.rst +++ b/removal_from_ansible.rst @@ -22,7 +22,7 @@ The community can remove a collection from the Ansible community package if the #. It depends on another collection included in X.0.0 but does not work with the actual version of it that is included, and there is no content in the collection that still works. -If the collection is broken, it can be removed from Ansible (X+1).0.0 under the following conditions: +We remove broken collections from Ansible (X+1).0.0 under the following conditions: #. The collection seems to be unmaintained and nobody fixes the problems. #. The plan to remove the collection in the next major Ansible release is publicized at least two months before the (X+1).0.0 release, and at least one month before the first (X+1).0.0 beta release. The removal must be announced in multiple places: From a1f305f1fac449304bfffdc95cca0947512077f1 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Wed, 6 Apr 2022 21:56:41 +0200 Subject: [PATCH 06/17] Rewrite. --- removal_from_ansible.rst | 108 +++++++++++++++++++++++++++++++-------- 1 file changed, 88 insertions(+), 20 deletions(-) diff --git a/removal_from_ansible.rst b/removal_from_ansible.rst index 4f5eda7..368a4e5 100644 --- a/removal_from_ansible.rst +++ b/removal_from_ansible.rst @@ -11,37 +11,79 @@ Sometimes the Ansible community removes a collection from the Ansible package. W In cases of emergency (for example, a serious security vulnerability that is not fixed in a collection) the `Ansible Community Engineering Steering Committee `_ can vote on emergency exceptions. In most cases, we follow the rules listed on this page. -Reasons to remove a collection -============================== +Broken collections +================== +The community can remove a collection from the Ansible community package if the collection is broken. -Collection is broken --------------------- +Identifying and removing a broken collection +-------------------------------------------- -The community can remove a collection from the Ansible community package if the collection is broken. A collection is considered broken if one of the following conditions is true: +Conditions for removal +~~~~~~~~~~~~~~~~~~~~~~ + +A collection is considered broken if one of the following conditions is true: #. It depends on another collection included in X.0.0 but does not work with the actual version of it that is included, and there is no content in the collection that still works. We remove broken collections from Ansible (X+1).0.0 under the following conditions: #. The collection seems to be unmaintained and nobody fixes the problems. -#. The plan to remove the collection in the next major Ansible release is publicized at least two months before the (X+1).0.0 release, and at least one month before the first (X+1).0.0 beta release. The removal must be announced in multiple places: -- included in the Ansible changelog -- announced in The Bullhorn -The announcement must state the reasons for the proposed removal and alert maintainers and the Ansible community that, to prevent the removal, the collection urgently needs new maintainers who can fix the problems. +#. The plan to remove the collection in the next major Ansible release is publicized at least two months before the (X+1).0.0 release, and at least one month before the first (X+1).0.0 beta release (feature freeze). + +Process +~~~~~~~ + +The announcement mentioned below must state the reasons for the proposed removal and alert maintainers and the Ansible community that, to prevent the removal, the collection urgently needs new maintainers who can fix the problems. + +#. Announce upcoming removal in the Ansible changelog (``https://github.com/ansible-community/ansible-build-data/blob/main//changelog.yaml``). +#. Announce upcoming removal in the collection's issue tracker. +#. Announce upcoming removal in The Bullhorn. +#. Remove from ``ansible.in`` for the next major version (``https://github.com/ansible-community/ansible-build-data/blob/main//ansible.in``). +#. Remove form ``collection-meta.yaml`` for the next major release (``https://github.com/ansible-community/ansible-build-data/blob/main//collection-meta.yaml``). +#. Once the first alpha of Ansible X+1 is to be released: document actual removal in the Ansible changelog (``https://github.com/ansible-community/ansible-build-data/blob/main//changelog.yaml``). + +Cancelling removal of a broken collection +----------------------------------------- -Conditions under which the collection can stay in the Ansible package before removal in Ansible X+1: +Conditions +~~~~~~~~~~ #. The issues have to be fixed and a new release (bugfix, minor or major) has to be made before the Ansible X+1 feature freeze. #. Someone has to promise to maintain the collection and prevent a similar situation at least for some time. +Process +~~~~~~~ + +#. Update the removal issue in the collection's issue tracker, and close the issue. +#. Announce cancelled removal in The Bullhorn. +#. Re-add collection to ``ansible.in`` for the next major release (``https://github.com/ansible-community/ansible-build-data/blob/main//ansible.in``). +#. Re-add collection to ``collection-meta.yaml`` for the next major release (``https://github.com/ansible-community/ansible-build-data/blob/main//collection-meta.yaml``). + +Re-adding collection to Ansible +------------------------------- + +Conditions +~~~~~~~~~~ + Conditions under which the collections can be re-included in the Ansible package without going through the `full inclusion process `_: #. The issues have to be fixed and a new release has to be made before the Ansible X+2 feature freeze. #. Someone has to promise to maintain the collection and prevent a similar situation at least for some time. -Collection is unmaintained --------------------------- +Process +~~~~~~~ + +#. Follow regular process of adding a new collection to Ansible. + +Unmaintained collections +======================== + +Identifying and removing an unmaintained collection +--------------------------------------------------- + +Conditions for removal +~~~~~~~~~~~~~~~~~~~~~~ A collection is considered unmaintained if multiple of the following conditions are satisfied: @@ -49,16 +91,42 @@ A collection is considered unmaintained if multiple of the following conditions #. CI has stopped passing (or even has not been running) for several months. #. Bug reports and bugfix PRs start piling up without being reviewed. -There is no complete formal definition of an unmaintained collection. To start the process of removing an unmaintained collection, the following must be done in the following order: - -#. The appearance that the collection is no longer maintained and might be removed from the Ansible package has to be announced both in The Bullhorn and in the collection's issue tracker. -#. The Ansible Community Engineering Steering Committee (SC) must look at the collection and vote that it considers it unmaintained. This must happen at least four weeks after the notice has appeared in the collection's issue tracker and in The Bullhorn, and the vote must be open for at least one week. -#. If the SC votes that the collection seems to unmaintained, another announcement is made in the collection's issue tracker, in The Bullhorn, and in the Ansible changelog that it will be removed from Ansible Y release. Here Y must be X+1 if Ansible X.0.0 will be released next, or Y must be X+2 if Ansible X.0.0 has already been released. This means that the announcement of impending removal will be active for at least one major release cycle of Ansible. +There is no complete formal definition of an unmaintained collection. -Conditions under which the collection can stay in the Ansible package before removal in Ansible X+1: +Process +~~~~~~~ +#. The appearance that the collection is no longer maintained and might be removed from the Ansible package has to be announced both in The Bullhorn and in the collection's issue tracker. +#. At least four weeks after the notice appeared in The Bullhorn and the collection's issue tracker, the Ansible Community Engineering Steering Committee (SC) must look at the collection and vote that it considers it unmaintained. The vote must be open for at least one week. +#. If the SC does not votes that the collection seems to be unmaintained, the process is stopped. The issue needs to be updated accordingly. +#. If X.0.0 will be released next, set Y=X+1. If X.0.0 has already been released, but (X+1).0.0 has not yet been released, set Y=X+2. +#. Announce upcoming removal from Ansible Y in the Ansible changelog (``https://github.com/ansible-community/ansible-build-data/blob/main//changelog.yaml``). +#. Announce upcoming removal from Ansible Y in the collection's issue tracker. +#. Announce upcoming removal from Ansible Y in The Bullhorn. +#. Remove from ``ansible.in`` for Ansible Y (``https://github.com/ansible-community/ansible-build-data/blob/main//ansible.in``). +#. Remove form ``collection-meta.yaml`` for Ansible Y (``https://github.com/ansible-community/ansible-build-data/blob/main//collection-meta.yaml``). +#. Once the first alpha of Ansible Y is to be released: document actual removal in the Ansible changelog (``https://github.com/ansible-community/ansible-build-data/blob/main//changelog.yaml``). + +Cancelling removal of an unmaintained collection +------------------------------------------------ + +Conditions +~~~~~~~~~~ + +#. Ansible Y has not yet been released. #. One or multiple maintainers step up, or return, to clean up the collection's state. #. There have been concrete results made by new maintainers (for example, CI has been fixed, the collection has been released, pull request authors have got meaningful feedback). -#. The Steering Committee votes on whether the result is acceptable. A negative vote must come with a good explanation why the clean up work has not been sufficient. -Once the collection has been removed from Ansible Y.0.0, it needs to go through the full inclusion process to be re-added to the Ansible package. Exceptions are only possible if the Steering Committee votes on them, and it is in the discretion of the Steering Committee to deny a fast re-entry without going through the full review process. +Process +~~~~~~~ + +#. The Steering Committee votes on whether the result is acceptable. +#. A negative vote must come with a good explanation why the clean up work has not been sufficient. In that case, this process stops. +#. If the Steering Committee does not vote against still removing the collection (this includes the case that the vote did not reach quorum), proceed as follows. +#. Re-add collection to ``ansible.in`` for Ansible Y (``https://github.com/ansible-community/ansible-build-data/blob/main//ansible.in``). +#. Re-add collection to ``collection-meta.yaml`` for Ansible Y (``https://github.com/ansible-community/ansible-build-data/blob/main//collection-meta.yaml``). + +Re-adding collection to Ansible +------------------------------- + +There is no simplified process. Once the collection has been removed from Ansible Y.0.0, it needs to go through the full inclusion process to be re-added to the Ansible package. Exceptions are only possible if the Steering Committee votes on them, and it is in the discretion of the Steering Committee to deny a fast re-entry without going through the full review process. From 4e7b2f5ff8ee772000d2955e76f73bd3b42b80a2 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Thu, 7 Apr 2022 07:12:54 +0200 Subject: [PATCH 07/17] Extract common processes. --- removal_from_ansible.rst | 60 +++++++++++++++++++++++++++++----------- 1 file changed, 44 insertions(+), 16 deletions(-) diff --git a/removal_from_ansible.rst b/removal_from_ansible.rst index 368a4e5..4c19659 100644 --- a/removal_from_ansible.rst +++ b/removal_from_ansible.rst @@ -11,6 +11,44 @@ Sometimes the Ansible community removes a collection from the Ansible package. W In cases of emergency (for example, a serious security vulnerability that is not fixed in a collection) the `Ansible Community Engineering Steering Committee `_ can vote on emergency exceptions. In most cases, we follow the rules listed on this page. +General processes +================= + +This section describes some general processes that will be referred to below. + +_announce_removal: + +Announcing upcoming removal +--------------------------- + +#. Announce upcoming removal in the Ansible changelog (``https://github.com/ansible-community/ansible-build-data/blob/main//changelog.yaml``). + See the following link for an `example on how to add changelog entries to the Ansible changelog `__. +#. Announce upcoming removal in the collection's issue tracker. +#. Announce upcoming removal in The Bullhorn. + +_remove_collection: + +Removing a collection +--------------------- + +To remove a collection from Ansible version X.0.0: + +#. Remove from ``ansible.in`` (``https://github.com/ansible-community/ansible-build-data/blob/main//ansible.in``). +#. Remove from ``collection-meta.yaml`` (``https://github.com/ansible-community/ansible-build-data/blob/main//collection-meta.yaml``). +#. Document actual removal for the first/next alpha of Ansible X.0.0 in the Ansible changelog (``https://github.com/ansible-community/ansible-build-data/blob/main//changelog.yaml``). + See the following link for an `example on how to add changelog entries to the Ansible changelog `__. + +_readd_collection: + +Re-adding a collection +---------------------- + +Re-adding a collection to Ansible works the same as adding it in the first place. See the `process of adding a new collection to Ansible `_ for reference. + +#. Re-add collection to ``ansible.in`` (``https://github.com/ansible-community/ansible-build-data/blob/main//ansible.in``). +#. Re-add collection to ``collection-meta.yaml`` (``https://github.com/ansible-community/ansible-build-data/blob/main//collection-meta.yaml``). +#. If the removal was announced in the Ansible changelog for a version that has not yet been released (``https://github.com/ansible-community/ansible-build-data/blob/main//changelog.yaml``), remove the announcement. + Broken collections ================== @@ -36,12 +74,8 @@ Process The announcement mentioned below must state the reasons for the proposed removal and alert maintainers and the Ansible community that, to prevent the removal, the collection urgently needs new maintainers who can fix the problems. -#. Announce upcoming removal in the Ansible changelog (``https://github.com/ansible-community/ansible-build-data/blob/main//changelog.yaml``). -#. Announce upcoming removal in the collection's issue tracker. -#. Announce upcoming removal in The Bullhorn. -#. Remove from ``ansible.in`` for the next major version (``https://github.com/ansible-community/ansible-build-data/blob/main//ansible.in``). -#. Remove form ``collection-meta.yaml`` for the next major release (``https://github.com/ansible-community/ansible-build-data/blob/main//collection-meta.yaml``). -#. Once the first alpha of Ansible X+1 is to be released: document actual removal in the Ansible changelog (``https://github.com/ansible-community/ansible-build-data/blob/main//changelog.yaml``). +#. Announce upcoming removal in Ansible X+1 as described in :ref:``. +#. Remove collection from Ansible X+1 as described in :ref:``. Cancelling removal of a broken collection ----------------------------------------- @@ -57,8 +91,7 @@ Process #. Update the removal issue in the collection's issue tracker, and close the issue. #. Announce cancelled removal in The Bullhorn. -#. Re-add collection to ``ansible.in`` for the next major release (``https://github.com/ansible-community/ansible-build-data/blob/main//ansible.in``). -#. Re-add collection to ``collection-meta.yaml`` for the next major release (``https://github.com/ansible-community/ansible-build-data/blob/main//collection-meta.yaml``). +#. Re-add collection to Ansible X+1 as described in :ref:`readd_collection`. Re-adding collection to Ansible ------------------------------- @@ -100,12 +133,8 @@ Process #. At least four weeks after the notice appeared in The Bullhorn and the collection's issue tracker, the Ansible Community Engineering Steering Committee (SC) must look at the collection and vote that it considers it unmaintained. The vote must be open for at least one week. #. If the SC does not votes that the collection seems to be unmaintained, the process is stopped. The issue needs to be updated accordingly. #. If X.0.0 will be released next, set Y=X+1. If X.0.0 has already been released, but (X+1).0.0 has not yet been released, set Y=X+2. -#. Announce upcoming removal from Ansible Y in the Ansible changelog (``https://github.com/ansible-community/ansible-build-data/blob/main//changelog.yaml``). -#. Announce upcoming removal from Ansible Y in the collection's issue tracker. -#. Announce upcoming removal from Ansible Y in The Bullhorn. -#. Remove from ``ansible.in`` for Ansible Y (``https://github.com/ansible-community/ansible-build-data/blob/main//ansible.in``). -#. Remove form ``collection-meta.yaml`` for Ansible Y (``https://github.com/ansible-community/ansible-build-data/blob/main//collection-meta.yaml``). -#. Once the first alpha of Ansible Y is to be released: document actual removal in the Ansible changelog (``https://github.com/ansible-community/ansible-build-data/blob/main//changelog.yaml``). +#. Announce upcoming removal from Ansible Y as described in :ref:``. +#. Remove collection from Ansible Y as described in :ref:``. Cancelling removal of an unmaintained collection ------------------------------------------------ @@ -123,8 +152,7 @@ Process #. The Steering Committee votes on whether the result is acceptable. #. A negative vote must come with a good explanation why the clean up work has not been sufficient. In that case, this process stops. #. If the Steering Committee does not vote against still removing the collection (this includes the case that the vote did not reach quorum), proceed as follows. -#. Re-add collection to ``ansible.in`` for Ansible Y (``https://github.com/ansible-community/ansible-build-data/blob/main//ansible.in``). -#. Re-add collection to ``collection-meta.yaml`` for Ansible Y (``https://github.com/ansible-community/ansible-build-data/blob/main//collection-meta.yaml``). +#. Re-add collection to Ansible Y as described in :ref:`readd_collection`. Re-adding collection to Ansible ------------------------------- From 20be039225ce8712a9a57bfc242bf5f72cb7e67f Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Thu, 7 Apr 2022 07:16:41 +0200 Subject: [PATCH 08/17] Fix labels. --- removal_from_ansible.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/removal_from_ansible.rst b/removal_from_ansible.rst index 4c19659..a42ceb0 100644 --- a/removal_from_ansible.rst +++ b/removal_from_ansible.rst @@ -16,7 +16,7 @@ General processes This section describes some general processes that will be referred to below. -_announce_removal: +.. _announce_removal: Announcing upcoming removal --------------------------- @@ -26,7 +26,7 @@ Announcing upcoming removal #. Announce upcoming removal in the collection's issue tracker. #. Announce upcoming removal in The Bullhorn. -_remove_collection: +.. _remove_collection: Removing a collection --------------------- @@ -38,7 +38,7 @@ To remove a collection from Ansible version X.0.0: #. Document actual removal for the first/next alpha of Ansible X.0.0 in the Ansible changelog (``https://github.com/ansible-community/ansible-build-data/blob/main//changelog.yaml``). See the following link for an `example on how to add changelog entries to the Ansible changelog `__. -_readd_collection: +.. _readd_collection: Re-adding a collection ---------------------- From 44b0ad1f56af1817fe74657021973e144d2b3938 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Thu, 7 Apr 2022 07:18:03 +0200 Subject: [PATCH 09/17] Fix refs. --- removal_from_ansible.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/removal_from_ansible.rst b/removal_from_ansible.rst index a42ceb0..e56eb1a 100644 --- a/removal_from_ansible.rst +++ b/removal_from_ansible.rst @@ -74,8 +74,8 @@ Process The announcement mentioned below must state the reasons for the proposed removal and alert maintainers and the Ansible community that, to prevent the removal, the collection urgently needs new maintainers who can fix the problems. -#. Announce upcoming removal in Ansible X+1 as described in :ref:``. -#. Remove collection from Ansible X+1 as described in :ref:``. +#. Announce upcoming removal in Ansible X+1 as described in :ref:`announce_removal`. +#. Remove collection from Ansible X+1 as described in :ref:`remove_collection`. Cancelling removal of a broken collection ----------------------------------------- @@ -133,8 +133,8 @@ Process #. At least four weeks after the notice appeared in The Bullhorn and the collection's issue tracker, the Ansible Community Engineering Steering Committee (SC) must look at the collection and vote that it considers it unmaintained. The vote must be open for at least one week. #. If the SC does not votes that the collection seems to be unmaintained, the process is stopped. The issue needs to be updated accordingly. #. If X.0.0 will be released next, set Y=X+1. If X.0.0 has already been released, but (X+1).0.0 has not yet been released, set Y=X+2. -#. Announce upcoming removal from Ansible Y as described in :ref:``. -#. Remove collection from Ansible Y as described in :ref:``. +#. Announce upcoming removal from Ansible Y as described in :ref:`announce_removal`. +#. Remove collection from Ansible Y as described in :ref:`remove_collection`. Cancelling removal of an unmaintained collection ------------------------------------------------ From 9cefc8bd50f8ec8091349b9afc8bad2308c7852b Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Thu, 7 Apr 2022 12:30:48 +0200 Subject: [PATCH 10/17] Apply suggestions from code review Co-authored-by: Andrew Klychkov --- removal_from_ansible.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/removal_from_ansible.rst b/removal_from_ansible.rst index e56eb1a..c8e30c2 100644 --- a/removal_from_ansible.rst +++ b/removal_from_ansible.rst @@ -89,7 +89,7 @@ Conditions Process ~~~~~~~ -#. Update the removal issue in the collection's issue tracker, and close the issue. +#. Update the removal issue in the collection's issue tracker and close the issue. #. Announce cancelled removal in The Bullhorn. #. Re-add collection to Ansible X+1 as described in :ref:`readd_collection`. @@ -107,7 +107,7 @@ Conditions under which the collections can be re-included in the Ansible package Process ~~~~~~~ -#. Follow regular process of adding a new collection to Ansible. +#. Follow `regular process of adding a new collection to Ansible `_. Unmaintained collections ======================== From 864fb23e559d837b1e76c43974e97716e9bbd98c Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Sun, 10 Apr 2022 13:50:11 +0200 Subject: [PATCH 11/17] Update removal_from_ansible.rst Co-authored-by: Andrew Klychkov --- removal_from_ansible.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/removal_from_ansible.rst b/removal_from_ansible.rst index c8e30c2..3741817 100644 --- a/removal_from_ansible.rst +++ b/removal_from_ansible.rst @@ -7,7 +7,7 @@ Ansible Community Package Collections Removal Process Overview ======== -Sometimes the Ansible community removes a collection from the Ansible package. We try to do this only rarely. This document describes why we might remove a collection from the `Ansible community package `_ (`build data `_). +Sometimes the Ansible community removes a collection from the Ansible package for stability, legal, or security reasons. This document describes why we might remove a collection from the `Ansible community package `_ (`build data `_). In cases of emergency (for example, a serious security vulnerability that is not fixed in a collection) the `Ansible Community Engineering Steering Committee `_ can vote on emergency exceptions. In most cases, we follow the rules listed on this page. From 209715b9e88f6d59d0ccc576e51124469cc344c3 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Sun, 10 Apr 2022 13:51:12 +0200 Subject: [PATCH 12/17] Update removal_from_ansible.rst Co-authored-by: Andrew Klychkov --- removal_from_ansible.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/removal_from_ansible.rst b/removal_from_ansible.rst index 3741817..59b8f28 100644 --- a/removal_from_ansible.rst +++ b/removal_from_ansible.rst @@ -157,4 +157,4 @@ Process Re-adding collection to Ansible ------------------------------- -There is no simplified process. Once the collection has been removed from Ansible Y.0.0, it needs to go through the full inclusion process to be re-added to the Ansible package. Exceptions are only possible if the Steering Committee votes on them, and it is in the discretion of the Steering Committee to deny a fast re-entry without going through the full review process. +There is no simplified process. Once the collection has been removed from Ansible Y.0.0, it needs to go through the full inclusion process to be re-added to the Ansible package. Exceptions are only possible if the Steering Committee votes on them. The Steering Committee can approve or deny a fast re-entry without going through the full review process. From cc46ab394725d6e6142bbac73c8a007c69921049 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Mon, 11 Apr 2022 20:49:23 +0200 Subject: [PATCH 13/17] Apply suggestions from code review Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> --- removal_from_ansible.rst | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/removal_from_ansible.rst b/removal_from_ansible.rst index 59b8f28..ac3e5c1 100644 --- a/removal_from_ansible.rst +++ b/removal_from_ansible.rst @@ -1,3 +1,5 @@ +.. _removal_from_ansible:: + ***************************************************** Ansible Community Package Collections Removal Process ***************************************************** @@ -14,7 +16,12 @@ In cases of emergency (for example, a serious security vulnerability that is not General processes ================= -This section describes some general processes that will be referred to below. +The general process of removing a collection follows these steps: + +#. announcing an upcoming removal of a collection +#. removing the collection +#. when appropriate, re-adding the collection + .. _announce_removal: From ae096ab770ab5b59f3744f3c1f0a71de6826808e Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Tue, 12 Apr 2022 06:42:15 +0200 Subject: [PATCH 14/17] Get rid of :ref: style references. --- removal_from_ansible.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/removal_from_ansible.rst b/removal_from_ansible.rst index ac3e5c1..b4577fd 100644 --- a/removal_from_ansible.rst +++ b/removal_from_ansible.rst @@ -81,8 +81,8 @@ Process The announcement mentioned below must state the reasons for the proposed removal and alert maintainers and the Ansible community that, to prevent the removal, the collection urgently needs new maintainers who can fix the problems. -#. Announce upcoming removal in Ansible X+1 as described in :ref:`announce_removal`. -#. Remove collection from Ansible X+1 as described in :ref:`remove_collection`. +#. `Announce upcoming removal in Ansible X+1 `_. +#. `Remove collection from Ansible X+1 `_. Cancelling removal of a broken collection ----------------------------------------- @@ -98,7 +98,7 @@ Process #. Update the removal issue in the collection's issue tracker and close the issue. #. Announce cancelled removal in The Bullhorn. -#. Re-add collection to Ansible X+1 as described in :ref:`readd_collection`. +#. `Re-add collection to Ansible X+1 `_. Re-adding collection to Ansible ------------------------------- @@ -140,8 +140,8 @@ Process #. At least four weeks after the notice appeared in The Bullhorn and the collection's issue tracker, the Ansible Community Engineering Steering Committee (SC) must look at the collection and vote that it considers it unmaintained. The vote must be open for at least one week. #. If the SC does not votes that the collection seems to be unmaintained, the process is stopped. The issue needs to be updated accordingly. #. If X.0.0 will be released next, set Y=X+1. If X.0.0 has already been released, but (X+1).0.0 has not yet been released, set Y=X+2. -#. Announce upcoming removal from Ansible Y as described in :ref:`announce_removal`. -#. Remove collection from Ansible Y as described in :ref:`remove_collection`. +#. `Announce upcoming removal from Ansible Y `_. +#. `Remove collection from Ansible Y `_. Cancelling removal of an unmaintained collection ------------------------------------------------ @@ -159,7 +159,7 @@ Process #. The Steering Committee votes on whether the result is acceptable. #. A negative vote must come with a good explanation why the clean up work has not been sufficient. In that case, this process stops. #. If the Steering Committee does not vote against still removing the collection (this includes the case that the vote did not reach quorum), proceed as follows. -#. Re-add collection to Ansible Y as described in :ref:`readd_collection`. +#. `Re-add collection to Ansible Y `_. Re-adding collection to Ansible ------------------------------- From 8d9dedb9123a3bbbdddf7844d5e16a9ac2c92923 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Tue, 12 Apr 2022 06:52:17 +0200 Subject: [PATCH 15/17] Make rst2html happy, hopefully also making GH's RST renderer happy. --- removal_from_ansible.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/removal_from_ansible.rst b/removal_from_ansible.rst index b4577fd..c40922c 100644 --- a/removal_from_ansible.rst +++ b/removal_from_ansible.rst @@ -81,8 +81,8 @@ Process The announcement mentioned below must state the reasons for the proposed removal and alert maintainers and the Ansible community that, to prevent the removal, the collection urgently needs new maintainers who can fix the problems. -#. `Announce upcoming removal in Ansible X+1 `_. -#. `Remove collection from Ansible X+1 `_. +#. `Announce upcoming removal in Ansible X+1 `_. +#. `Remove collection from Ansible X+1 `_. Cancelling removal of a broken collection ----------------------------------------- @@ -98,7 +98,7 @@ Process #. Update the removal issue in the collection's issue tracker and close the issue. #. Announce cancelled removal in The Bullhorn. -#. `Re-add collection to Ansible X+1 `_. +#. `Re-add collection to Ansible X+1 `_. Re-adding collection to Ansible ------------------------------- @@ -140,8 +140,8 @@ Process #. At least four weeks after the notice appeared in The Bullhorn and the collection's issue tracker, the Ansible Community Engineering Steering Committee (SC) must look at the collection and vote that it considers it unmaintained. The vote must be open for at least one week. #. If the SC does not votes that the collection seems to be unmaintained, the process is stopped. The issue needs to be updated accordingly. #. If X.0.0 will be released next, set Y=X+1. If X.0.0 has already been released, but (X+1).0.0 has not yet been released, set Y=X+2. -#. `Announce upcoming removal from Ansible Y `_. -#. `Remove collection from Ansible Y `_. +#. `Announce upcoming removal from Ansible Y `_. +#. `Remove collection from Ansible Y `_. Cancelling removal of an unmaintained collection ------------------------------------------------ @@ -159,7 +159,7 @@ Process #. The Steering Committee votes on whether the result is acceptable. #. A negative vote must come with a good explanation why the clean up work has not been sufficient. In that case, this process stops. #. If the Steering Committee does not vote against still removing the collection (this includes the case that the vote did not reach quorum), proceed as follows. -#. `Re-add collection to Ansible Y `_. +#. `Re-add collection to Ansible Y `_. Re-adding collection to Ansible ------------------------------- From 130944d4e056ec829f97a48de223522929292201 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Tue, 12 Apr 2022 06:57:13 +0200 Subject: [PATCH 16/17] Fix document link. --- removal_from_ansible.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/removal_from_ansible.rst b/removal_from_ansible.rst index c40922c..9a95ac0 100644 --- a/removal_from_ansible.rst +++ b/removal_from_ansible.rst @@ -1,4 +1,4 @@ -.. _removal_from_ansible:: +.. _removal_from_ansible: ***************************************************** Ansible Community Package Collections Removal Process From 2f93b93b9918ee446eb484a3eaf6d7bd047811c6 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Wed, 13 Apr 2022 20:07:12 +0200 Subject: [PATCH 17/17] Update removal_from_ansible.rst Co-authored-by: Mario Lenz --- removal_from_ansible.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/removal_from_ansible.rst b/removal_from_ansible.rst index 9a95ac0..b1b9a7e 100644 --- a/removal_from_ansible.rst +++ b/removal_from_ansible.rst @@ -138,7 +138,7 @@ Process #. The appearance that the collection is no longer maintained and might be removed from the Ansible package has to be announced both in The Bullhorn and in the collection's issue tracker. #. At least four weeks after the notice appeared in The Bullhorn and the collection's issue tracker, the Ansible Community Engineering Steering Committee (SC) must look at the collection and vote that it considers it unmaintained. The vote must be open for at least one week. -#. If the SC does not votes that the collection seems to be unmaintained, the process is stopped. The issue needs to be updated accordingly. +#. If the SC does not vote that the collection seems to be unmaintained, the process is stopped. The issue needs to be updated accordingly. #. If X.0.0 will be released next, set Y=X+1. If X.0.0 has already been released, but (X+1).0.0 has not yet been released, set Y=X+2. #. `Announce upcoming removal from Ansible Y `_. #. `Remove collection from Ansible Y `_.