airbrake_deployment: Add version param (#583)

* airbrake_deployment: Add version param

The aibrake v4 API allows for distinct `version` and `revision` params.
The `revision` param is meant to indicate a revision from the version
control system (such as a Git hash), whereas the `version` param is
meant to be a version number (such as 1.2.3). This is especially
noticeable in the Airbrake UI where revisions are truncated to 7
characters, and used to build GitHub style diff links (such as
689a25edcf...e54dd3a01f).

* Add link to PR in changelog

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

* Add version_added to version param

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

* Add type to version's argument_spec

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

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

changelogs/fragments/airbrake_deployment_add_version.yml

@@ -0,0 +1,3 @@
+---
+minor_changes:
+  - "airbrake_deployment - add ``version`` param; clarified docs on ``revision`` param (https://github.com/ansible-collections/community.general/pull/583)."

plugins/modules/monitoring/airbrake_deployment.py

@@ -48,9 +48,15 @@ options:
     type: str
   revision:
     description:
-      - A hash, number, tag, or other identifier showing what revision was deployed
+      - A hash, number, tag, or other identifier showing what revision from version control was deployed
     required: false
     type: str
+  version:
+    description:
+      - A string identifying what version was deployed
+    required: false
+    type: str
+    version_added: '1.0.0'
   url:
     description:
       - Optional URL to submit the notification to. Use to send notifications to Airbrake-compliant tools like Errbit.
@@ -81,6 +87,15 @@ EXAMPLES = '''
     environment: staging
     user: ansible
     revision: '4.2'
+
+- name: Notify airbrake about an app deployment, using git hash as revision
+  airbrake_deployment:
+    project_id: '12345'
+    project_key: 'AAAAAA'
+    environment: staging
+    user: ansible
+    revision: 'e54dd3a01f2c421b558ef33b5f79db936e2dcf15'
+    version: '0.2.0'
 '''
 
 from ansible.module_utils.basic import AnsibleModule
@@ -103,6 +118,7 @@ def main():
             user=dict(required=False),
             repo=dict(required=False),
             revision=dict(required=False),
+            version=dict(required=False, type='str'),
             url=dict(required=False, default='https://api.airbrake.io/api/v4/projects/'),
             validate_certs=dict(default=True, type='bool'),
         ),
@@ -119,6 +135,7 @@ def main():
         module.exit_json(changed=True)
 
     if module.params["token"]:
+        # v2 API documented at https://airbrake.io/docs/legacy-xml-api/#tracking-deploys
         if module.params["environment"]:
             params["deploy[rails_env]"] = module.params["environment"]
 
@@ -131,6 +148,8 @@ def main():
         if module.params["revision"]:
             params["deploy[scm_revision]"] = module.params["revision"]
 
+        # version not supported in v2 API; omit
+
         module.deprecate("Parameter 'token' is deprecated since community.general 0.2.0. Please remove "
                          "it and use 'project_id' and 'project_key' instead",
                          version='3.0.0', collection_name='community.general')  # was Ansible 2.14
@@ -148,6 +167,7 @@ def main():
         response, info = fetch_url(module, url, data=data)
 
     if module.params["project_id"] and module.params["project_key"]:
+        # v4 API documented at https://airbrake.io/docs/api/#create-deploy-v4
         if module.params["environment"]:
             params["environment"] = module.params["environment"]
 
@@ -160,6 +180,9 @@ def main():
         if module.params["revision"]:
             params["revision"] = module.params["revision"]
 
+        if module.params["version"]:
+            params["version"] = module.params["version"]
+
         # Build deploy url
         url = module.params.get('url') + module.params["project_id"] + '/deploys?key=' + module.params["project_key"]
         json_body = module.jsonify(params)