MH cause_changes: deprecate params (#8791)

* MH cause_changes: deprecate params

* add changelog frag

* Update changelogs/fragments/8791-mh-cause-changes-param-depr.yml

Co-authored-by: Felix Fontein <felix@fontein.de>

---------

Co-authored-by: Felix Fontein <felix@fontein.de>

changelogs/fragments/8791-mh-cause-changes-param-depr.yml

@@ -0,0 +1,4 @@
+minor_changes:
+  - jira - replace deprecated params when using decorator ``cause_changes`` (https://github.com/ansible-collections/community.general/pull/8791).
+deprecated_features:
+  - MH decorator cause_changes module utils - deprecate parameters ``on_success`` and ``on_failure`` (https://github.com/ansible-collections/community.general/pull/8791).

plugins/module_utils/mh/deco.py

@@ -14,6 +14,7 @@ from ansible_collections.community.general.plugins.module_utils.mh.exceptions im
 
 
 def cause_changes(on_success=None, on_failure=None, when=None):
+    # Parameters on_success and on_failure are deprecated and should be removed in community.general 12.0.0
 
     def deco(func):
         @wraps(func)

plugins/modules/jira.py

@@ -544,7 +544,7 @@ class JIRA(StateModuleHelper):
         self.vars.uri = self.vars.uri.strip('/')
         self.vars.set('restbase', self.vars.uri + '/rest/api/2')
 
-    @cause_changes(on_success=True)
+    @cause_changes(when="success")
     def operation_create(self):
         createfields = {
             'project': {'key': self.vars.project},
@@ -562,7 +562,7 @@ class JIRA(StateModuleHelper):
         url = self.vars.restbase + '/issue/'
         self.vars.meta = self.post(url, data)
 
-    @cause_changes(on_success=True)
+    @cause_changes(when="success")
     def operation_comment(self):
         data = {
             'body': self.vars.comment
@@ -578,7 +578,7 @@ class JIRA(StateModuleHelper):
         url = self.vars.restbase + '/issue/' + self.vars.issue + '/comment'
         self.vars.meta = self.post(url, data)
 
-    @cause_changes(on_success=True)
+    @cause_changes(when="success")
     def operation_worklog(self):
         data = {
             'comment': self.vars.comment
@@ -594,7 +594,7 @@ class JIRA(StateModuleHelper):
         url = self.vars.restbase + '/issue/' + self.vars.issue + '/worklog'
         self.vars.meta = self.post(url, data)
 
-    @cause_changes(on_success=True)
+    @cause_changes(when="success")
     def operation_edit(self):
         data = {
             'fields': self.vars.fields
@@ -602,7 +602,7 @@ class JIRA(StateModuleHelper):
         url = self.vars.restbase + '/issue/' + self.vars.issue
         self.vars.meta = self.put(url, data)
 
-    @cause_changes(on_success=True)
+    @cause_changes(when="success")
     def operation_update(self):
         data = {
             "update": self.vars.fields,
@@ -624,7 +624,7 @@ class JIRA(StateModuleHelper):
 
         self.vars.meta = self.get(url)
 
-    @cause_changes(on_success=True)
+    @cause_changes(when="success")
     def operation_transition(self):
         # Find the transition id
         turl = self.vars.restbase + '/issue/' + self.vars.issue + "/transitions"
@@ -657,7 +657,7 @@ class JIRA(StateModuleHelper):
         url = self.vars.restbase + '/issue/' + self.vars.issue + "/transitions"
         self.vars.meta = self.post(url, data)
 
-    @cause_changes(on_success=True)
+    @cause_changes(when="success")
     def operation_link(self):
         data = {
             'type': {'name': self.vars.linktype},
@@ -667,7 +667,7 @@ class JIRA(StateModuleHelper):
         url = self.vars.restbase + '/issueLink/'
         self.vars.meta = self.post(url, data)
 
-    @cause_changes(on_success=True)
+    @cause_changes(when="success")
     def operation_attach(self):
         v = self.vars
         filename = v.attachment.get('filename')

tests/unit/plugins/module_utils/test_module_helper.py

@@ -119,6 +119,11 @@ def test_variable_meta_change():
     assert vd.has_changed('d')
 
 
+#
+# DEPRECATION NOTICE
+# Parameters on_success and on_failure are deprecated and will be removed in community.genral 12.0.0
+# Remove testcases with those params when releasing 12.0.0
+#
 CAUSE_CHG_DECO_PARAMS = ['deco_args', 'expect_exception', 'expect_changed']
 CAUSE_CHG_DECO = dict(
     none_succ=dict(deco_args={}, expect_exception=False, expect_changed=None),