Draft: Orphaning and Retirement of Ansible modules

gistfile1.txt

RETIRED MODULES

What is module retirement? 

It is the flagging and ultimate removal of a module because it is no longer useful and may actively harm or confuse users by its continuing existence.

Why might a module be retired? There are three fundamental reasons:

* Because the module supports a product/project that is no longer
  supported / useful / exists.

* Because the module has been relocated to a new location. 

* Because the module has been obsoleted by another module.

In these cases, the retired module should ultimately provide warning information for a time, with redirection information, and then ultimately be removed from the Ansible collection or distribution.

Stories:

* As a community, we need to have a process to decide whether a module that has been marked for retirement should actually be retired, or whether it should be orphaned instead.

* As a contributor, I need to be able to notify the community that a module should be retired.

* As a user, I need to know immediately and repeatedly that I'm using a module that is about to retired, with enough time so that I can plan for its ultimate removal.

* As a user, I need to know when I consult the documentation for a module that it is retired or about to be retired.

---

ORPHANED MODULES

What is module orphaning?

Module orphaning is the process of denoting that a module is no longer being actively maintained, which allows us to provide warnings to users, and allows us to solicit for new maintainers for the module.

Why might a module be orphaned?

* Because the contributor expresses the explicit desire to no longer maintain the module;

* Because the contributor has demonstrated an unwillingness or an inability to maintain the module according to accepted community standards.

In both of these cases, the users should be made aware that they are using orphaned content, so that they are aware of the additional potential risk incurred by using such content.

Stories:

* As a user, I would like to know when I'm using a module that it's not currently being actively maintained.

* As a potential contributor, I would like to know how the process to take over maintainership of a currently orphaned module.

* As a user, I'd like to know when I consult the documentation that a module I'm planning to use is orphaned.

* As a contributor, I'd like an easy process to step away from maintaining a package.

* As a community, we need a process that allows us to mark a package as orphaned when there is evidence that it is not being properly maintained.

* As a community, we would like a process that advertises currently orphaned modules so that we can solicit for new maintainers.

---

ADDITIONAL RESOURCES

https://fedoraproject.org/wiki/Orphaned_package_that_need_new_maintainers

https://fedoraproject.org/wiki/How_to_remove_a_package_at_end_of_life

Among other things, we definitely need a guide how a user can become a maintainer.
We have BOTMETA.yml where teams, containing github accounts of their members, are listed and the bot mentions them when a related issue/pr is created.
So, would be cool to have something like "if you want to become a module's maintainer, please,
go to there and there, ask that guy... you need to do this and that... A maintainer gets automatically generated emails when issues/PRs happens, their shipit are counted by the bot for automerge.." and other important information.

https://docs.ansible.com/ansible/2.9/community/maintainers.html contains info only how to step down as a maintainer:)
Maybe it is somewhere else, i haven't found.
Would be good to have something mentioned https://docs.ansible.com/ansible/latest/user_guide/modules_support.html there as well.

When i started to maintain modules, i had no idea how i could become a maintainer.
Maybe somebody suggested adding me to BOTMETA.yml but if there are not active contributors whose mind the idea can cross
we can miss potential maintainers.

People should know how to become maintainers, it can be a special section on https://docs.ansible.com/ansible/2.9/community/maintainers.html

And put the link on every module's page.

I believe that the "how a user can become a maintainer" will become a separate "orphaned packages" proposal, which I will make separately.

sounds good

Several more practical points:

1. We have maintainers listed in BOTMETA.yml, yes, @gundalow @felixfontein?
   Would be also good to have maintainers on corresponding doc pages:

• it would allow users to see who maintain the module and to text them directly
• it could be good supplementary motivation for potential contributors to support modules to see their names on Ansible official doc pages, imo

2. We could add to "Why might a module be orphaned?" also (meaning) an opinion of core team member
   that a module is not currently maintained based on a number of related issues/prs
   that have no feedback from the module's maintainer(s).
   I mean cases when it's obvious from the context that a module/group of modules is not maintained at all.

3. How to mark a module as orphaned?
   a) maybe, to add a new special subsection to module doc part like seealso, e.g. orphaned: yes and
   then such a module could be added automatically to a list of orphaned modules somewhere in the doc or github
   like in fedora project (btw https://src.fedoraproject.org/user/orphan) returns Internal Server Error)
   b) ?

4. Would be also good to add references to corresponding WG / community pinboards (where they exist) to seealso sections.

We definitely should expand this document for abandoned collections as well

What is the expected behavior of a orphaned / retired module ? does it works as before or just throw a warning / fatal message the state of the module and the possible alternate module to use ?