add doc changes

Author: surendrababuravella

changelogs/fragments/2167_playbook_upgrade_validator_role.yml

@@ -0,0 +1,3 @@
+minor_changes:
+   - playbook_upgrade_validator - Adding a role that automatically scans the playbooks in the directory and advises of migration actions.
+     (https://github.com/ansible-collections/ibm_zos_core/pull/2399)

plugins/modules/playbook_upgrade_validator.py

@@ -20,7 +20,7 @@
 version_added: "1.0.0"
 author:
   - "Ravella Surendra Babu (@surendrababuravella)"
-short_description: Validate playbooks against ibm_zos_core 2.0
+short_description: Validates playbooks against ibm_zos_core 2.0 and provides migration actions.
 description:
   - Scans one or more Ansible playbooks to identify deprecated or renamed parameters
     based on migration rules for IBM z/OS core collection version 2.0.
@@ -33,7 +33,8 @@
     type: bool
   migration_map:
     description:
-      - File path where validation results should be written in JSON format.
+      - A structured set of migration rules that specifies deprecated, renamed, and modified parameters
+        to help upgrade playbooks from ibm_zos_core 1.x to 2.0.
     required: true
     type: dict
   output_path:
@@ -62,14 +63,38 @@
 '''
 
 RETURN = r'''
+changed:
+  description:
+    - Always false as there is no state changes happen in this process.
+  returned: always
+  type: bool
 output_path:
-  description: Path where the validation report was written.
+  description: File path where validation results should be written in JSON format.
+  returned: always
+  type: str
+playbook_path:
+  description: The path to the directory containing one or more Ansible playbooks.
   returned: always
   type: str
 results:
-  description: List of all issues found across all playbooks.
+  description: List of issues identified in all scanned playbooks, along with detailed information.
   returned: always
   type: list
+  sample:
+    [
+        {
+            "line": 9,
+            "migration_actions": [
+                "[MUST_FIX] Param 'force_lock' is renamed to 'force' in zos_copy",
+                "[MUST_FIX] Param 'is_binary' is renamed to 'binary' in zos_copy",
+                "[MUST_FIX] Param 'force' is renamed to 'replace' in zos_copy"
+            ],
+            "module": "zos_copy",
+            "play_name": "Execute z/OS modules",
+            "playbook": "/path/to/playbook/copy_file.yml",
+            "task_name": "copy file to z/os"
+        }
+    ]
 '''
 
 from ansible.module_utils.basic import AnsibleModule

roles/playbook_upgrade_validator/docs/doc_playbook_upgrade_validator

@@ -11,52 +11,83 @@
 
 DOCUMENTATION = r'''
 ---
-role: job_status
+module: playbook_upgrade_validator
+version_added: "1.0.0"
 author:
   - "Ravella Surendra Babu (@surendrababuravella)"
 short_description: Validates playbooks against ibm_zos_core 2.0 and provides migration actions.
 description:
   - Scans one or more Ansible playbooks to identify deprecated or renamed parameters
     based on migration rules for IBM z/OS core collection version 2.0.
-  - Provides line numbers, affected modules, and suggests corrective actions.
+  - Provides line numbers, affected modules, and suggested corrective actions.
 options:
-  playbook_path:
+  ignore_response_params:
     description:
-      - The path to the directory containing one or more Ansible playbooks.
+      - Indicates whether information about response parameter changes should be included.
+    default: false
+    type: bool
+  migration_map:
+    description:
+      - A structured set of migration rules that specifies deprecated, renamed, and modified parameters
+        to help upgrade playbooks from ibm_zos_core 1.x to 2.0.
     required: true
-    type: str
+    type: dict
   output_path:
     description:
       - File path where validation results should be written in JSON format.
     required: true
     type: str
-  ignore_response_params:
+  playbook_path:
     description:
-      - Indicates whether information about response parameter changes should be included.
-    default: false
-    type: bool
+      - The path to the directory containing one or more Ansible playbooks.
+    required: true
+    type: str
 notes:
   - Designed to assist migration of playbooks from older IBM z/OS core collection versions to 2.0.
   - Supports reading tasks, blocks, and nested includes.
 '''
 
 EXAMPLES = r'''
 - name: execute playbook_upgrade_validator role
-  include_role: 
+  include_role:
     name: ibm.ibm_zos_core.playbook_upgrade_validator
   vars:
     playbook_path: "/path/to/playbooks/*.yml"
-    output_path: "{{ role_path }}/reports/validation_report.json"
+    output_path: "/path/to/reports/validation_report.json"
     ignore_response_params: false
 '''
 
 RETURN = r'''
+changed:
+  description:
+    - Always false as there is no state changes happen in this process.
+  returned: always
+  type: bool
 output_path:
-  description: Path where the validation report was written.
+  description: File path where validation results should be written in JSON format.
+  returned: always
+  type: str
+playbook_path:
+  description: The path to the directory containing one or more Ansible playbooks.
   returned: always
   type: str
 results:
-  description: List of all issues found across all playbooks.
+  description: List of issues identified in all scanned playbooks, along with detailed information.
   returned: always
   type: list
+  sample:
+    [
+        {
+            "line": 9,
+            "migration_actions": [
+                "[MUST_FIX] Param 'force_lock' is renamed to 'force' in zos_copy",
+                "[MUST_FIX] Param 'is_binary' is renamed to 'binary' in zos_copy",
+                "[MUST_FIX] Param 'force' is renamed to 'replace' in zos_copy"
+            ],
+            "module": "zos_copy",
+            "play_name": "Execute z/OS modules",
+            "playbook": "/path/to/playbook/copy_file.yml",
+            "task_name": "copy file to z/os"
+        }
+    ]
 '''

tests/sanity/ignore-2.15.txt

@@ -26,3 +26,4 @@ plugins/modules/zos_archive.py validate-modules:missing-gplv3-license # Licensed
 plugins/modules/zos_unarchive.py validate-modules:missing-gplv3-license # Licensed under Apache 2.0
 plugins/modules/zos_zfs_resize.py validate-modules:missing-gplv3-license # Licensed under Apache 2.0
 plugins/modules/zos_started_task.py validate-modules:missing-gplv3-license # Licensed under Apache 2.0
+plugins/modules/playbook_upgrade_validator.py validate-modules:missing-gplv3-license # Licensed under Apache 2.0

tests/sanity/ignore-2.16.txt

@@ -26,5 +26,5 @@ plugins/modules/zos_volume_init.py validate-modules:missing-gplv3-license # Lice
 plugins/modules/zos_archive.py validate-modules:missing-gplv3-license # Licensed under Apache 2.0
 plugins/modules/zos_unarchive.py validate-modules:missing-gplv3-license # Licensed under Apache 2.0
 plugins/modules/zos_zfs_resize.py validate-modules:missing-gplv3-license # Licensed under Apache 2.0
-plugins/modules/playbook_upgrade_validator.py validate-modules:missing-gplv3-license # Licensed under Apache 2.0
 plugins/modules/zos_started_task.py validate-modules:missing-gplv3-license # Licensed under Apache 2.0
+plugins/modules/playbook_upgrade_validator.py validate-modules:missing-gplv3-license # Licensed under Apache 2.0

tests/sanity/ignore-2.17.txt

@@ -26,5 +26,5 @@ plugins/modules/zos_volume_init.py validate-modules:missing-gplv3-license # Lice
 plugins/modules/zos_archive.py validate-modules:missing-gplv3-license # Licensed under Apache 2.0
 plugins/modules/zos_unarchive.py validate-modules:missing-gplv3-license # Licensed under Apache 2.0
 plugins/modules/zos_zfs_resize.py validate-modules:missing-gplv3-license # Licensed under Apache 2.0
-plugins/modules/playbook_upgrade_validator.py validate-modules:missing-gplv3-license # Licensed under Apache 2.0
 plugins/modules/zos_started_task.py validate-modules:missing-gplv3-license # Licensed under Apache 2.0
+plugins/modules/playbook_upgrade_validator.py validate-modules:missing-gplv3-license # Licensed under Apache 2.0

tests/sanity/ignore-2.18.txt

@@ -26,5 +26,5 @@ plugins/modules/zos_volume_init.py validate-modules:missing-gplv3-license # Lice
 plugins/modules/zos_archive.py validate-modules:missing-gplv3-license # Licensed under Apache 2.0
 plugins/modules/zos_unarchive.py validate-modules:missing-gplv3-license # Licensed under Apache 2.0
 plugins/modules/zos_zfs_resize.py validate-modules:missing-gplv3-license # Licensed under Apache 2.0
-plugins/modules/playbook_upgrade_validator.py validate-modules:missing-gplv3-license # Licensed under Apache 2.0
 plugins/modules/zos_started_task.py validate-modules:missing-gplv3-license # Licensed under Apache 2.0
+plugins/modules/playbook_upgrade_validator.py validate-modules:missing-gplv3-license # Licensed under Apache 2.0

tests/sanity/ignore-2.19.txt

@@ -26,4 +26,5 @@ plugins/modules/zos_volume_init.py validate-modules:missing-gplv3-license # Lice
 plugins/modules/zos_archive.py validate-modules:missing-gplv3-license # Licensed under Apache 2.0
 plugins/modules/zos_unarchive.py validate-modules:missing-gplv3-license # Licensed under Apache 2.0
 plugins/modules/zos_zfs_resize.py validate-modules:missing-gplv3-license # Licensed under Apache 2.0
+plugins/modules/zos_started_task.py validate-modules:missing-gplv3-license # Licensed under Apache 2.0
 plugins/modules/playbook_upgrade_validator.py validate-modules:missing-gplv3-license # Licensed under Apache 2.0