Update return documentation, deprecate records value - vm_nic module

records will be replaced by record.

Author: PolonaM

changelogs/fragments/return_documentation_update_vm_nic.yml

@@ -0,0 +1,3 @@
+---
+major_changes:
+  - Deprecate records value and add record value in vm_nic module return values. (https://github.com/ScaleComputing/HyperCoreAnsibleCollection/pull/183)

plugins/modules/vm_nic.py

@@ -69,6 +69,8 @@
           - Is network interface connected or not.
 notes:
   - C(check_mode) is not supported.
+  - Return value C(record) is added in version 1.2.0, and deprecates return value C(records).
+    Return value C(records) will be removed in future release.
 """
 
 EXAMPLES = r"""
@@ -136,18 +138,69 @@
 """
 
 RETURN = r"""
+record:
+  description:
+    - The created or changed record for nic on a specified virtual machine.
+  returned: success
+  type: dict
+  contains:
+    uuid:
+      description: Unique identifier
+      type: str
+      sample: 07a2a68a-0afa-4718-9c6f-00a39d08b67e
+    vlan:
+      description: VLAN tag of the interface
+      type: int
+      sample: 15
+    type:
+      description: Virtualized network device types
+      type: str
+      sample: virtio
+    mac:
+      description: MAC address of the virtual network device
+      type: str
+      sample: 12-34-56-78-AB
+    connected:
+      description: Enabled and can make connections
+      type: bool
+      sample: true
+    ipv4_addresses:
+      description: IPv4 addresses registered with this device
+      type: list
+      elements: str
+      sample: 192.0.2.1
 records:
   description:
     - The created or changed record for nic on a specified virtual machine.
+    - This value is deprecated and will be removed in a future release. Please use record instead.
   returned: success
-  type: list
-  sample:
-    - uuid: 07a2a68a-0afa-4718-9c6f-00a39d08b67e
-      vlan: 15
-      type: virtio
-      mac: 12-34-56-78-AB
-      connected: true
-      ipv4_addresses: []
+  type: dict
+  contains:
+    uuid:
+      description: Unique identifier
+      type: str
+      sample: 07a2a68a-0afa-4718-9c6f-00a39d08b67e
+    vlan:
+      description: VLAN tag of the interface
+      type: int
+      sample: 15
+    type:
+      description: Virtualized network device types
+      type: str
+      sample: virtio
+    mac:
+      description: MAC address of the virtual network device
+      type: str
+      sample: 12-34-56-78-AB
+    connected:
+      description: Enabled and can make connections
+      type: bool
+      sample: true
+    ipv4_addresses:
+      description: IPv4 addresses registered with this device
+      type: list
+      elements: str
+      sample: 192.0.2.1
 """
 
 from ansible.module_utils.basic import AnsibleModule
@@ -278,12 +331,24 @@ def main():
         ),
     )
 
+    module.deprecate(
+        "The 'records' return value is being renamed to 'record'."
+        "Please use 'record' since 'records' will be removed in future release."
+        "But for now both values are being returned to allow users to migrate their automation.",
+        version="3.0.0",
+        collection_name="scale_computing.hypercore",
+    )
+
     try:
         client = Client.get_client(module.params["cluster_instance"])
         rest_client = RestClient(client=client)
-        changed, records, diff, reboot = run(module, rest_client)
+        changed, record, diff, reboot = run(module, rest_client)
         module.exit_json(
-            changed=changed, records=records, diff=diff, vm_rebooted=reboot
+            changed=changed,
+            records=record,
+            record=record,
+            diff=diff,
+            vm_rebooted=reboot,
         )
     except errors.ScaleComputingError as e:
         module.fail_json(msg=str(e))

tests/unit/plugins/modules/test_vm_nic.py

@@ -197,6 +197,7 @@ def test_minimal_set_of_params(self, run_main_with_reboot, mocker):
         assert results == {
             "changed": False,
             "records": {},
+            "record": {},
             "diff": {"before": {}, "after": {}},
             "vm_rebooted": False,
         }