Proposal: Module Rename Lifecycle

[ryansb]

Proposal: Module Rename Lifecycle

Author: Ryan "@ryansb" Scott Brown

Date: 2016/05/11

• Status: New
• Proposal type: Process
• Targeted Release: 2.2
• Associated PR: none
• Estimated time to implement: ???

Motivation

There are some modules that don't conform to naming conventions that have either developed since the module was merged or weren't enforced when the module was merged. This proposal is to add a guideline to the contrib/community guide that covers how to rename a module, and a deprecation cycle for renames.

Problems

If a module has a name that needs to be changed, the development team needs a way of changing the name without breaking playbooks and creating sad users. Some examples of names we'd want to change are the plural module names from this spec or the AWS route53 module which is just the service name, not a resource within the service.

Solution proposal

This proposal matches the 4-cycle deprecation process.

After being deprecated, the old name could be reused if needed, though there's not much of a reason to reuse a name if it was deprecated for not conforming to a guideline.

When deprecated, the module code should be moved to a file matching the new name, and a code block along these lines should be added to the execution path:

if module._name == 'ping':
    module.deprecate("The 'ping' module is being renamed 'newping'", version=2.6)

In the above example, the ping module is being renamed to newping.

Example

Let's walk through the process if someone were to rename a module during the 2.3 dev cycle.

1. In 2.3 release, add module.deprecate call to the module, and git mv the file to the new name (example.py -> newname.py) and add a symlink to alias the old name, _example.py.
2. For 2.4, 2.5, and 2.6 the module is available with the deprecation warning
3. In the 2.7 dev cycle the alias with the old name is removed, making that name available again.

[ryansb]

Updates from discussion in today's meeting:

• Make the deprecation warning phase last two cycles
• Add a deprecation section to the CHANGELOG at release
• Add a deprecation section to the 2.2 roadmap to plan what modules will be removed this cycle
• Need a design (with code) for a place to implement warning of deprecations, and keep canonical list of deprecated/removed module names and their new aliases (assignee @ryansb)

[wimnat]

@ryansb is there anywhere where you are collating a list of modules that should be renamed? I have a few suggestions...

[wimnat]

@ryansb any update on this one?

[ryansb]

@wimnat updated with new outcomes from last core meeting.

[abadger]

Looks good.