actually show plugin config warnings/deprecations (#82593)

previouslly we recorded but did not show to avoid spam
since we could not dedup from forks, that was already
fixed in another PR so now we can show/display them.

Also:
  * funcitonalize deprecation msg construct from docs
  * reuse formatting func in cli
  * normalize alternatives: most of the code used intended plural
    but some and most data/tests used the singular
  * update schemas and tests

Co-authored-by: Matt Davis <6775756+nitzmahone@users.noreply.github.com>
Co-authored-by: Felix Fontein <felix@fontein.de>

8 files changed, 287 insertions, 0 deletions

diff --git a/test/integration/targets/deprecations/aliases b/test/integration/targets/deprecations/aliases
new file mode 100644
index 0000000000..8278ec8bcc
--- /dev/null
+++ b/test/integration/targets/deprecations/aliases
@@ -0,0 +1,2 @@
+shippable/posix/group3
+context/controller
diff --git a/test/integration/targets/deprecations/cache_plugins/notjsonfile.py b/test/integration/targets/deprecations/cache_plugins/notjsonfile.py
new file mode 100644
index 0000000000..dfa20158f7
--- /dev/null
+++ b/test/integration/targets/deprecations/cache_plugins/notjsonfile.py
@@ -0,0 +1,82 @@
+# (c) 2020 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import annotations
+
+DOCUMENTATION = '''
+    cache: notjsonfile
+    short_description: NotJSON cache plugin
+    description: This cache uses is NOT JSON
+    author: Ansible Core (@ansible-core)
+    version_added: 0.7.0
+    options:
+      _uri:
+        required: True
+        description:
+          - Path in which the cache plugin will save the JSON files
+        env:
+          - name: ANSIBLE_CACHE_PLUGIN_CONNECTION
+            version_added: 1.2.0
+        ini:
+          - key: fact_caching_connection
+            section: notjsonfile_cache
+          - key: fact_caching_connection
+            section: defaults
+      _prefix:
+        description: User defined prefix to use when creating the JSON files
+        env:
+          - name: ANSIBLE_CACHE_PLUGIN_PREFIX
+            version_added: 1.1.0
+        ini:
+          - key: fact_caching_prefix
+            section: defaults
+          - key: fact_caching_prefix
+            section: notjson_cache
+            deprecated:
+              alternative: section is notjsonfile_cache
+              why: Another test deprecation
+              removed_at_date: '2050-01-01'
+          - key: fact_caching_prefix
+            section: notjsonfile_cache
+      _timeout:
+        default: 86400
+        description: Expiration timeout for the cache plugin data
+        env:
+          - name: ANSIBLE_CACHE_PLUGIN_TIMEOUT
+          - name: ANSIBLE_NOTJSON_CACHE_PLUGIN_TIMEOUT
+            deprecated:
+              alternative: do not use a variable
+              why: Test deprecation
+              version: '3.0.0'
+        ini:
+          - key: fact_caching_timeout
+            section: defaults
+          - key: fact_caching_timeout
+            section: notjsonfile_cache
+        vars:
+          - name: notsjonfile_fact_caching_timeout
+            version_added: 1.5.0
+        type: integer
+      removeme:
+        default: 86400
+        description: Expiration timeout for the cache plugin data
+        deprecated:
+            alternative: cause i need to test it
+            why: Test deprecation
+            version: '2.0.0'
+        env:
+          - name: ANSIBLE_NOTJSON_CACHE_PLUGIN_REMOVEME
+'''
+
+from ansible.plugins.cache import BaseFileCacheModule
+
+
+class CacheModule(BaseFileCacheModule):
+    """
+    A caching module backed by json files.
+    """
+    def _dump(self):
+        pass
+
+    def _load(self):
+        pass
diff --git a/test/integration/targets/deprecations/entry_key_deprecated.cfg b/test/integration/targets/deprecations/entry_key_deprecated.cfg
new file mode 100644
index 0000000000..2a49bb8d72
--- /dev/null
+++ b/test/integration/targets/deprecations/entry_key_deprecated.cfg
@@ -0,0 +1,2 @@
+[testing]
+deprecated=false
diff --git a/test/integration/targets/deprecations/entry_key_deprecated2.cfg b/test/integration/targets/deprecations/entry_key_deprecated2.cfg
new file mode 100644
index 0000000000..02798c9056
--- /dev/null
+++ b/test/integration/targets/deprecations/entry_key_deprecated2.cfg
@@ -0,0 +1,3 @@
+[testing]
+# ini key not deprecated, but parent setting is
+valid2=true
diff --git a/test/integration/targets/deprecations/entry_key_not_deprecated.cfg b/test/integration/targets/deprecations/entry_key_not_deprecated.cfg
new file mode 100644
index 0000000000..53f2b1369c
--- /dev/null
+++ b/test/integration/targets/deprecations/entry_key_not_deprecated.cfg
@@ -0,0 +1,2 @@
+[testing]
+valid=false
diff --git a/test/integration/targets/deprecations/library/removeoption.py b/test/integration/targets/deprecations/library/removeoption.py
new file mode 100644
index 0000000000..9f08792fcd
--- /dev/null
+++ b/test/integration/targets/deprecations/library/removeoption.py
@@ -0,0 +1,78 @@
+# -*- coding: utf-8 -*-
+# Copyright: Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import annotations
+
+
+DOCUMENTATION = r'''
+---
+module: removeoption
+short_description: noop
+description: does nothing, test for removal of option
+options:
+  one:
+    description:
+    - first option
+    type: bool
+    default: no
+  two:
+    description:
+    - second option
+    deprecated:
+        removed_in: '3.30'
+        why: cause i wanna test this!
+        alternatives: none needed
+notes:
+- Just noop to test module deprecation
+seealso:
+- module: willremove
+author:
+- Ansible Core Team
+attributes:
+    action:
+      support: full
+    async:
+      support: full
+    bypass_host_loop:
+      support: none
+    check_mode:
+      support: full
+    diff_mode:
+      support: none
+    platform:
+      platforms: all
+'''
+
+EXAMPLES = r'''
+- name: useless
+  remove_option:
+    one: true
+    two: /etc/file.conf
+'''
+
+RETURN = r'''
+'''
+
+from ansible.module_utils.basic import AnsibleModule
+
+
+def main():
+    module = AnsibleModule(
+        argument_spec=dict(
+            one=dict(type='bool', default='no'),
+            two=dict(type='str', removed_in_version='3.30'),
+        ),
+        supports_check_mode=True
+    )
+
+    one = module.params['one']
+    two = module.params['two']
+
+    result = {'yolo': 'lola'}
+
+    module.exit_json(**result)
+
+
+if __name__ == '__main__':
+    main()
diff --git a/test/integration/targets/deprecations/library/willremove.py b/test/integration/targets/deprecations/library/willremove.py
new file mode 100644
index 0000000000..0c5810d850
--- /dev/null
+++ b/test/integration/targets/deprecations/library/willremove.py
@@ -0,0 +1,79 @@
+# -*- coding: utf-8 -*-
+# Copyright: Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import annotations
+
+
+DOCUMENTATION = r'''
+---
+module: willremove
+version_added: histerical
+short_description: does nothing
+description: does nothing, this is deprecation test
+deprecated:
+    removed_in: '3.30'
+    why: cause i wanna!
+    alternatives: no soup for you!
+options:
+  one:
+    description:
+    - first option
+    type: bool
+    default: no
+  two:
+    description:
+    - second option
+notes:
+- Just noop to test module deprecation
+seealso:
+- module: removeoption
+author:
+- Ansible Core Team
+attributes:
+    action:
+      support: full
+    async:
+      support: full
+    bypass_host_loop:
+      support: none
+    check_mode:
+      support: full
+    diff_mode:
+      support: none
+    platform:
+      platforms: all
+'''
+
+EXAMPLES = r'''
+- name: useless
+  willremove:
+    one: true
+    two: /etc/file.conf
+'''
+
+RETURN = r'''
+'''
+
+from ansible.module_utils.basic import AnsibleModule
+
+
+def main():
+    module = AnsibleModule(
+        argument_spec=dict(
+            one=dict(type='bool', default='no'),
+            two=dict(type='str'),
+        ),
+        supports_check_mode=True
+    )
+
+    one = module.params['one']
+    two = module.params['two']
+
+    result = {'yolo': 'lola'}
+
+    module.exit_json(**result)
+
+
+if __name__ == '__main__':
+    main()
diff --git a/test/integration/targets/deprecations/runme.sh b/test/integration/targets/deprecations/runme.sh
new file mode 100755
index 0000000000..f16d4937a7
--- /dev/null
+++ b/test/integration/targets/deprecations/runme.sh
@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+
+set -eux -o pipefail
+
+export ANSIBLE_DEPRECATION_WARNINGS=True
+
+### check general config
+
+# check for entry key valid, no deprecation
+[ "$(ANSIBLE_CONFIG='entry_key_not_deprecated.cfg' ansible -m meta -a 'noop'  localhost 2>&1 | grep -c 'DEPRECATION')" -eq "0" ]
+
+# check for entry key deprecation, must be defined to trigger
+[ "$(ANSIBLE_CONFIG='entry_key_deprecated.cfg' ansible -m meta -a 'noop'  localhost 2>&1 | grep -c 'DEPRECATION')" -eq "1" ]
+
+# check for deprecation of entry itself, must be consumed to trigger
+[ "$(ANSIBLE_TEST_ENTRY2=1 ansible -m debug -a 'msg={{q("config", "_Z_TEST_ENTRY_2")}}' localhost  2>&1 | grep -c 'DEPRECATION')" -eq "1" ]
+
+# check for entry deprecation, just need key defined to trigger
+[ "$(ANSIBLE_CONFIG='entry_key_deprecated2.cfg' ansible -m meta -a 'noop'  localhost 2>&1 | grep -c 'DEPRECATION')" -eq "1" ]
+
+
+### check plugin config
+
+# force use of the test plugin
+export ANSIBLE_CACHE_PLUGIN_CONNECTION=/var/tmp
+export ANSIBLE_CACHE_PLUGIN=notjsonfile
+
+# check for plugin(s) config option and setting non deprecation
+[ "$(ANSIBLE_CACHE_PLUGIN_TIMEOUT=1 ansible -m meta -a 'noop'  localhost --playbook-dir ./ 2>&1 | grep -c 'DEPRECATION')" -eq "0" ]
+
+# check for plugin(s) config option setting deprecation
+[ "$(ANSIBLE_NOTJSON_CACHE_PLUGIN_TIMEOUT=1 ansible -m meta -a 'noop'  localhost --playbook-dir ./ 2>&1 | grep -c 'DEPRECATION')" -eq "1" ]
+
+# check for plugin(s) config option deprecation
+[ "$(ANSIBLE_NOTJSON_CACHE_PLUGIN_REMOVEME=1 ansible -m meta -a 'noop'  localhost --playbook-dir ./ 2>&1 | grep -c 'DEPRECATION')" -eq "1" ]
+
+# TODO: check for module deprecation
+# TODO: check for module option deprecation
+# TODO: check for plugin deprecation