Add automated playbook updater tool that implements the Porting Guide

# Proposal:

*Author*: John Barker <@gundalow>

*Date*: 2019-11-04

- Status: New
- Proposal type: Core
- Targeted release: Future, though could be in standarlone tool
- Associated PR: none yet
- Estimated time to implement: month?

## Motivation

Currently, each version of Ansible includes a [Porting Guide](https://docs.ansible.com/ansible/latest/porting_guides/porting_guides.html) containing manual steps that users are required to look at and manually update their Playbooks, or just keep on running `ansible-playbook` till the deprecation notices go away.

A [Porting Guide](https://docs.ansible.com/ansible/latest/porting_guides/porting_guide_2.9.html)

This can include things like:
* Module has been renamed from `foo` to `bar`
* A Module's argument has been updated from `foo` to `far`
* Change in functionality, such as the default option
* Language changes

### Size of Porting Guide

Rounded number of lines `porting_guide_2.x.rst`:
* 2.0: 400
* 2.3: 230
* 2.4: 230
* 2.5: 400
* 2.6: 110
* 2.7: 250
* 2.8: 560
* 2.9: 730

Partly the size is increasing as we get better at including things in the porting guide, partly as we are forcing users to change more per release.

This could be done in a way so Porting Guide fragments could be contained in Collections and pulled together to go alongside Ansible releases.

## Solution proposal

Create a tool to "upgrade" Playbooks from one version of Ansible to the next, similar to:
* phpcs
* Python's `2to3`
* Ruby's rubocop

Some of this could be automated, ie:

`porting_data_2.9.yml` (Steps needed to go from Ansible 2.8 to Ansible 2.9)

```yaml
renames:
modules:
- ec2_ami_find:
new_module: ec2_ami_facts
- kubernetes:
new_module: k8s_raw
- cs_instance_facts:
new_module: cs_instance_info
- net_banner: # Script can't fix this for you.
manual_message: Use the platform-specific [netos]_banner modules instead
lookup:
- redis_kv:
new_plugin: redism
module_changes:
- win_firewall_rule:
arg: force
removed: true
```

### Example upgrade

New tool `ansible-update` (or could be related to `ansible-lint`)

Think it terms of
```console
$ ansible-update -v .
Upgrading playbooks to Ansible 2.9 format
[I] roles/setup/tasks/main.yml:1 ec2_ami_find -> ec2_ami_facts
[E] roles/switch_basic/tasks/main.yaml:4 Manual update needed for `net_banner` Use the platform-specific [netos]_banner modules instead
$ git diff
```

```diff
diff --git a/roles/setup/tasks/main.yml b/roles/setup/tasks/main.yml
index 49111d4..c0fbfca 100644
--- a/roles/setup/tasks/main.yml
+++ b/roles/setup/tasks/main.yml
@@ -1,3 +1,3 @@
- name: gather information about an AMI using ami-id
- ec2_ami_facts:
+ ec2_ami_info:
image_ids: ami-5b488823
```

### Generating Docs

This, along with https://github.com/ansible/ansible/blob/816e194e375913537b31c2c8e2bd5baa6fdfb308/lib/ansible/modules/network/vyos/_vyos_interface.py#L36-L39 could be used to generate the Porting Guides.

Rather than a [list](https://docs.ansible.com/ansible/2.9/porting_guides/porting_guide_2.9.html#renamed-modules), this could be used to generate a table like [debops](https://docs.debops.org/en/master/news/upgrades.html#inventory-variable-changes) do, thanks drybjed for the suggestion.

## Dependencies (optional)
Explain any dependencies. This section is optional but could be helpful.
- Dependency #1
- Dependency #2

## Testing (optional)
* Various example old Playbooks with expected output

## Documentation (optional)
* yes, fixme

## Anything else?

Start with the linked Porting Guide examples, the porting_data_2.9.yml sketch, and the referenced lib/ansible/modules/network/vyos/_vyos_interface.py lines. Compare the proposed playbook transformation and manual-warning output with the “Various example old Playbooks with expected output” testing note; done means the proposed updater behavior and generated documentation are defined and testable.

Written by the indexing model from the issue text.