From baac82435d239cf0fc74a8c3a517de77db007221 Mon Sep 17 00:00:00 2001
From: Alexei Znamensky <russoz@gmail.com>
Date: Mon, 21 Jul 2025 21:16:31 +1200
Subject: [PATCH 1/3] cpanm: deprecate mode=compatibility

---
 plugins/modules/cpanm.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/plugins/modules/cpanm.py b/plugins/modules/cpanm.py
index 482183c0e0..3cf807ed5b 100644
--- a/plugins/modules/cpanm.py
+++ b/plugins/modules/cpanm.py
@@ -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='12.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'")

From 6b4a83052ddc827f1569e9032fb04e11e56cdc88 Mon Sep 17 00:00:00 2001
From: Alexei Znamensky <russoz@gmail.com>
Date: Mon, 21 Jul 2025 21:54:32 +1200
Subject: [PATCH 2/3] adjust docs

---
 plugins/modules/cpanm.py | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/plugins/modules/cpanm.py b/plugins/modules/cpanm.py
index 3cf807ed5b..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,7 +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='12.0.0', collection_name="community.general")
+            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'")

From 2e609008c3d6ac5190d0497ec95b141a6f0c9f48 Mon Sep 17 00:00:00 2001
From: Alexei Znamensky <russoz@gmail.com>
Date: Mon, 21 Jul 2025 21:58:46 +1200
Subject: [PATCH 3/3] add changelog frag

---
 changelogs/fragments/10434-cpanm-deprecate-compat-mode.yml | 2 ++
 1 file changed, 2 insertions(+)
 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).