puppet: deprecate param timeout (#11658)

* puppet: deprecate param timeout

* add changelog frag

* Update changelogs/fragments/11658-puppet-timeout-deprecation.yml

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

---------

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

changelogs/fragments/11658-puppet-timeout-deprecation.yml

@@ -0,0 +1,3 @@
+deprecated_features:
+  - puppet - the ``timeout`` parameter is deprecated and will be removed in community.general 14.0.0.
+    (https://github.com/ansible-collections/community.general/pull/11658).

plugins/module_utils/puppet.py

@@ -52,12 +52,11 @@ def puppet_runner(module: AnsibleModule) -> CmdRunner:
     # If this can be replaced with ansible `timeout` parameter in playbook,
     # then this function could be removed.
     def _prepare_base_cmd():
-        _tout_cmd = module.get_bin_path("timeout", False)
-        if _tout_cmd:
-            cmd = ["timeout", "-s", "9", module.params["timeout"], _puppet_cmd(module)]
-        else:
-            cmd = ["puppet"]
-        return cmd
+        if module.params["timeout"]:
+            _tout_cmd = module.get_bin_path("timeout", False)
+            if _tout_cmd:
+                return ["timeout", "-s", "9", module.params["timeout"], _puppet_cmd(module)]
+        return ["puppet"]
 
     def noop_func(v):
         return ["--noop"] if module.check_mode or v else ["--no-noop"]

plugins/modules/puppet.py

@@ -22,6 +22,9 @@ options:
   timeout:
     description:
       - How long to wait for C(puppet) to finish.
+      - This parameter is deprecated and will be removed in community.general 14.0.0.
+        Use the task-level C(timeout) keyword instead.
+        To suppress this deprecation warning, set O(timeout) to V("").
     type: str
     default: 30m
   puppetmaster:
@@ -240,6 +243,15 @@ def main():
     )
     p = module.params
 
+    if p["timeout"]:
+        module.deprecate(
+            'The "timeout" parameter is deprecated and will be removed in community.general 14.0.0. '
+            'Use the task-level "timeout" keyword instead. '
+            "To suppress this warning, set \"timeout: ''\" in the task.",
+            version="14.0.0",
+            collection_name="community.general",
+        )
+
     if p["manifest"]:
         if not os.path.exists(p["manifest"]):
             module.fail_json(msg=f"Manifest file {dict(manifest=p['manifest'])['manifest']} not found.")

tests/unit/plugins/modules/test_puppet.yaml

@@ -198,6 +198,33 @@ test_cases:
           rc: 0
           out: ''
           err: ''
+  - id: puppet_agent_timeout_empty
+    input:
+      timeout: ""
+    output:
+      changed: false
+    mocks:
+      run_command:
+        - command: [/testbin/puppet, config, print, agent_disabled_lockfile]
+          environ: *env-def
+          rc: 0
+          out: blah, anything
+          err: ''
+        - command:
+            - /testbin/puppet
+            - agent
+            - --onetime
+            - --no-daemonize
+            - --no-usecacheonfailure
+            - --no-splay
+            - --detailed-exitcodes
+            - --verbose
+            - --color
+            - '0'
+          environ: *env-def
+          rc: 0
+          out: ''
+          err: ''
   - id: puppet_agent_waitforlock
     input:
       waitforlock: 30