From cae94f9d5e69cc0a5fdf3aece0778e21e4b1a77f Mon Sep 17 00:00:00 2001
From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com>
Date: Fri, 9 Jun 2023 17:13:31 +0200
Subject: [PATCH] [PR #6650/61b88974 backport][stable-7] redhat_subscription:
 deprecate "pool" (#6657)

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.

(cherry picked from commit 61b889749e6cb955c75a773ce708eabc8765e1fe)

Co-authored-by: Pino Toscano <ptoscano@redhat.com>
---
 ...6650-redhat_subscription-deprecate-pool.yml |  5 +++++
 plugins/modules/redhat_subscription.py         | 18 +++++++++++++++---
 2 files changed, 20 insertions(+), 3 deletions(-)
 create mode 100644 changelogs/fragments/6650-redhat_subscription-deprecate-pool.yml

diff --git a/changelogs/fragments/6650-redhat_subscription-deprecate-pool.yml b/changelogs/fragments/6650-redhat_subscription-deprecate-pool.yml
new file mode 100644
index 0000000000..3bcffa5a48
--- /dev/null
+++ b/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).
diff --git a/plugins/modules/redhat_subscription.py b/plugins/modules/redhat_subscription.py
index 3340a3c9cf..87c805fe92 100644
--- a/plugins/modules/redhat_subscription.py
+++ b/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': {},