From e3467385fbe3f5ec338085491d7b002447183763 Mon Sep 17 00:00:00 2001
From: Alexei Znamensky <103110+russoz@users.noreply.github.com>
Date: Tue, 5 Aug 2025 05:58:59 +1200
Subject: [PATCH] cpanm: deprecate mode=compatibility (#10434)

* cpanm: deprecate mode=compatibility

* adjust docs

* add changelog frag
---
 .../10434-cpanm-deprecate-compat-mode.yml       |  2 ++
 plugins/modules/cpanm.py                        | 17 +++++++++--------
 2 files changed, 11 insertions(+), 8 deletions(-)
 create mode 100644 changelogs/fragments/10434-cpanm-deprecate-compat-mode.yml

diff --git a/changelogs/fragments/10434-cpanm-deprecate-compat-mode.yml b/changelogs/fragments/10434-cpanm-deprecate-compat-mode.yml
new file mode 100644
index 0000000000..84b6ecf471
--- /dev/null
+++ b/changelogs/fragments/10434-cpanm-deprecate-compat-mode.yml
@@ -0,0 +1,2 @@
+deprecated_features:
+  - cpanm - deprecate ``mode=compatibility``, ``mode=new`` should be used instead (https://github.com/ansible-collections/community.general/pull/10434).
diff --git a/plugins/modules/cpanm.py b/plugins/modules/cpanm.py
index 482183c0e0..788a554bf3 100644
--- a/plugins/modules/cpanm.py
+++ b/plugins/modules/cpanm.py
@@ -86,6 +86,14 @@ options:
     description:
       - Controls the module behavior. See notes below for more details.
       - The default changed from V(compatibility) to V(new) in community.general 9.0.0.
+      - 'O(mode=new): The O(name) parameter may refer to a module name, a distribution file, a HTTP URL or a git repository
+        URL as described in C(cpanminus) documentation. C(cpanm) version specifiers are recognized. This is the default mode
+        from community.general 9.0.0 onwards.'
+      - 'O(mode=compatibility): This was the default mode before community.general 9.0.0. O(name) must be either a module
+        name or a distribution file. If the perl module given by O(name) is installed (at the exact O(version) when specified),
+        then nothing happens. Otherwise, it is installed using the C(cpanm) executable. O(name) cannot be an URL, or a git
+        URL. C(cpanm) version specifiers do not work in this mode.'
+      - 'B(ATTENTION): V(compatibility) mode is deprecated and will be removed in community.general 13.0.0.'
     type: str
     choices: [compatibility, new]
     default: new
@@ -98,14 +106,6 @@ options:
     version_added: 3.0.0
 notes:
   - Please note that U(http://search.cpan.org/dist/App-cpanminus/bin/cpanm, cpanm) must be installed on the remote host.
-  - 'This module now comes with a choice of execution O(mode): V(compatibility) or V(new).'
-  - 'O(mode=compatibility): When using V(compatibility) mode, the module keeps backward compatibility. This was the default
-    mode before community.general 9.0.0. O(name) must be either a module name or a distribution file. If the perl module given
-    by O(name) is installed (at the exact O(version) when specified), then nothing happens. Otherwise, it is installed using
-    the C(cpanm) executable. O(name) cannot be an URL, or a git URL. C(cpanm) version specifiers do not work in this mode.'
-  - 'O(mode=new): When using V(new) mode, the module behaves differently. The O(name) parameter may refer to a module name,
-    a distribution file, a HTTP URL or a git repository URL as described in C(cpanminus) documentation. C(cpanm) version specifiers
-    are recognized. This is the default mode from community.general 9.0.0 onwards.'
 seealso:
   - name: C(cpanm) command manual page
     description: Manual page for the command.
@@ -211,6 +211,7 @@ class CPANMinus(ModuleHelper):
         if v.mode == "compatibility":
             if v.name_check:
                 self.do_raise("Parameter name_check can only be used with mode=new")
+            self.deprecate("'mode=compatibility' is deprecated, use 'mode=new' instead", version='13.0.0', collection_name="community.general")
         else:
             if v.name and v.from_path:
                 self.do_raise("Parameters 'name' and 'from_path' are mutually exclusive when 'mode=new'")