redhat_subscription: deprecate "pool" (#6650)

The "pool" option is slower to use, and the regexp may expand to broader
results than wanted. Because of that, deprecate it in favour of the
"pool_ids" options (which is much better), slating it for removal in
community.general 10.0.0.

changelogs/fragments/6650-redhat_subscription-deprecate-pool.yml

@@ -0,0 +1,5 @@
+deprecated_features:
+- |
+  redhat_subscription - the ``pool`` option is deprecated in favour of the
+  more precise and flexible ``pool_ids`` option
+  (https://github.com/ansible-collections/community.general/pull/6650).

plugins/modules/redhat_subscription.py

@@ -143,8 +143,16 @@ options:
     pool:
         description:
             - |
-              Specify a subscription pool name to consume.  Regular expressions accepted. Use I(pool_ids) instead if
-              possible, as it is much faster. Mutually exclusive with I(pool_ids).
+              Specify a subscription pool name to consume.  Regular expressions accepted.
+              Mutually exclusive with I(pool_ids).
+            - |
+              Please use I(pool_ids) instead: specifying pool IDs is much faster,
+              and it avoids to match new pools that become available for the
+              system and are not explicitly wanted.  Also, this option does not
+              support quantities.
+            - |
+              This option is deprecated for the reasons mentioned above,
+              and it will be removed in community.general 10.0.0.
         default: '^$'
         type: str
     pool_ids:
@@ -1091,7 +1099,11 @@ def main():
             'activationkey': {'no_log': True},
             'org_id': {},
             'environment': {},
-            'pool': {'default': '^$'},
+            'pool': {
+                'default': '^$',
+                'removed_in_version': '10.0.0',
+                'removed_from_collection': 'community.general',
+            },
             'pool_ids': {'default': [], 'type': 'list', 'elements': 'raw'},
             'consumer_type': {},
             'consumer_name': {},