Merge pull request #1559 from ansible-collections/doc-updates-for-readme

Doc updates for README , release notes and support matrix.

Author: richp405

README.md

@@ -36,7 +36,7 @@ To upgrade the collection to the latest available version, run the following com
 ansible-galaxy collection install ibm.ibm_zos_core --upgrade
 ```
 
-<br/>You can also install a specific version of the collection, for example, if you need to downgrade when something is broken in the latest version (please report an issue in this repository). Use the following syntax to install version 1.0.0:
+<br/>You can also install a specific version of the collection, for example, if you need to downgrade for some reason. Use the following syntax to install version 1.0.0:
 
 ```sh
 ansible-galaxy collection install ibm.ibm_zos_core:1.0.0
@@ -123,9 +123,10 @@ environment_vars:
 
 ## Testing
 
-All releases, including betas will meet the following test criteria.
+All releases, will meet the following test criteria.
 
 * 100% success for [Functional](https://github.com/ansible-collections/ibm_zos_core/tree/dev/tests/functional) tests.
+* 100% success for [Unit](https://github.com/ansible-collections/ibm_zos_core/tree/dev/tests/unit) tests.
 * 100% success for [Sanity](https://docs.ansible.com/ansible/latest/dev_guide/testing/sanity/index.html#all-sanity-tests) tests as part of[ansible-test](https://docs.ansible.com/ansible/latest/dev_guide/testing.html#run-sanity-tests).
 * 100% success for [pyflakes](https://github.com/PyCQA/pyflakes/blob/main/README.rst).
 * 100% success for [ansible-lint](https://ansible.readthedocs.io/projects/lint/) allowing only false positives.
@@ -153,9 +154,8 @@ If you would like to communicate with this community, you can do so through the
 * GitHub [discussions](https://github.com/ansible-collections/ibm_zos_core/discussions).
 * GitHub [issues](https://github.com/ansible-collections/ibm_zos_core/issues/new/choose).
 * [Ansible Forum](https://forum.ansible.com/), please use the `zos` tag to ensure proper awareness.
-* Discord [System Z Enthusiasts](https://forum.ansible.com/) room [ansible](https://discord.gg/nKC8F89v).
-* Matrix Ansible room [ansible-zos](#ansible-zos:matrix.org).
-* Ansible community Matrix [rooms](https://docs.ansible.com/ansible/latest/community/communication.html#general-channels).
+* Discord [System Z Enthusiasts](https://discord.gg/Kmy5QaUGbB) room [ansible](https://discord.gg/nHrDdRTC).
+* Matrix general usage questions [room](https://matrix.to/#/#users:ansible.com).
 
 ## Support
 
@@ -175,15 +175,15 @@ For Galaxy and GitHub users, to see the supported ansible-core versions, review
 
 <br/>The collection's changelogs can be reviewed in the following table.
 
-| Version  | Status                     | Release notes | Changelogs |
-|----------|----------------------------|---------------|------------|
-| 1.11.x   | In development (unreleased)| unreleased    | unreleased |
-| 1.10.x   | Current                    | [Release notes](https://ibm.github.io/z_ansible_collections_doc/ibm_zos_core/docs/source/release_notes.html#version-1-10-0)   | [Changelogs](https://github.com/ansible-collections/ibm_zos_core/blob/v1.10.0/CHANGELOG.rst) |
-| 1.9.x    | Released                   | [Release notes](https://ibm.github.io/z_ansible_collections_doc/ibm_zos_core/docs/source/release_notes.html#version-1-9-0)    | [Changelogs](https://github.com/ansible-collections/ibm_zos_core/blob/v1.9.0/CHANGELOG.rst)  |
-| 1.8.x    | Released                   | [Release notes](https://ibm.github.io/z_ansible_collections_doc/ibm_zos_core/docs/source/release_notes.html#version-1-8-0)    | [Changelogs](https://github.com/ansible-collections/ibm_zos_core/blob/v1.8.0/CHANGELOG.rst)  |
-| 1.7.x    | Released                   | [Release notes](https://ibm.github.io/z_ansible_collections_doc/ibm_zos_core/docs/source/release_notes.html#version-1-7-0)    | [Changelogs](https://github.com/ansible-collections/ibm_zos_core/blob/v1.7.0/CHANGELOG.rst)  |
-| 1.6.x    | Released                   | [Release notes](https://ibm.github.io/z_ansible_collections_doc/ibm_zos_core/docs/source/release_notes.html#version-1-6-0)    | [Changelogs](https://github.com/ansible-collections/ibm_zos_core/blob/v1.6.0/CHANGELOG.rst)  |
-| 1.5.x    | Released                   | [Release notes](https://ibm.github.io/z_ansible_collections_doc/ibm_zos_core/docs/source/release_notes.html#version-1-5-0)    | [Changelogs](https://github.com/ansible-collections/ibm_zos_core/blob/v1.5.0/CHANGELOG.rst)  |
+| Version  | Status         | Release notes | Changelogs |
+|----------|----------------|---------------|------------|
+| 1.11.x   | In development | unreleased    | unreleased |
+| 1.10.x   | Current        | [Release notes](https://ibm.github.io/z_ansible_collections_doc/ibm_zos_core/docs/source/release_notes.html#version-1-10-0)   | [Changelogs](https://github.com/ansible-collections/ibm_zos_core/blob/v1.10.0/CHANGELOG.rst) |
+| 1.9.x    | Released       | [Release notes](https://ibm.github.io/z_ansible_collections_doc/ibm_zos_core/docs/source/release_notes.html#version-1-9-0)    | [Changelogs](https://github.com/ansible-collections/ibm_zos_core/blob/v1.9.0/CHANGELOG.rst)  |
+| 1.8.x    | Released       | [Release notes](https://ibm.github.io/z_ansible_collections_doc/ibm_zos_core/docs/source/release_notes.html#version-1-8-0)    | [Changelogs](https://github.com/ansible-collections/ibm_zos_core/blob/v1.8.0/CHANGELOG.rst)  |
+| 1.7.x    | Released       | [Release notes](https://ibm.github.io/z_ansible_collections_doc/ibm_zos_core/docs/source/release_notes.html#version-1-7-0)    | [Changelogs](https://github.com/ansible-collections/ibm_zos_core/blob/v1.7.0/CHANGELOG.rst)  |
+| 1.6.x    | Released       | [Release notes](https://ibm.github.io/z_ansible_collections_doc/ibm_zos_core/docs/source/release_notes.html#version-1-6-0)    | [Changelogs](https://github.com/ansible-collections/ibm_zos_core/blob/v1.6.0/CHANGELOG.rst)  |
+| 1.5.x    | Released       | [Release notes](https://ibm.github.io/z_ansible_collections_doc/ibm_zos_core/docs/source/release_notes.html#version-1-5-0)    | [Changelogs](https://github.com/ansible-collections/ibm_zos_core/blob/v1.5.0/CHANGELOG.rst)  |
 
 ## Related Information
 

changelogs/fragments/1552-readme-support-updates.yml

@@ -0,0 +1,10 @@
+trivial:
+  - README - updated formatting and how it was written to be clearer.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/1559).
+
+  - release_notes.rst - removed known issue that was incorrect for v1.9.x.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/1559).
+
+  - releases_maintenance.rst - Added new lifecycle stages and supported
+    shell types.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/1559).

docs/source/release_notes.rst

@@ -276,9 +276,6 @@ Several modules have reported UTF-8 decoding errors when interacting with result
 An undocumented option **size** was defined in module **zos_data_set**, this has been removed to satisfy collection certification, use the intended
 and documented **space_primary** option.
 
-In the past, choices could be defined in either lower or upper case. Now, only the case that is identified in the docs can be set,
-this is so that the collection can continue to maintain certified status.
-
 Availability
 ------------
 

docs/source/resources/releases_maintenance.rst

@@ -6,16 +6,60 @@
 Releases and maintenance
 ========================
 
-This table describes the collections release dates, dependency versions and End of Life dates (EOL).
+This section describes the collections release dates, dependency versions and End of Life dates (EOL)
+and support coverage.
 
 The ``ibm_zos_core`` collection is developed and released on a flexible release cycle; generally, each quarter
 a beta is released followed by a GA version. Occasionally, the cycle may be extended to properly implement and
 test larger changes before a new release is made available.
 
 End of Life for this collection is generally a 2-year cycle unless a dependency reaches EOL prior to the 2 years.
-For example, if a collection has released and its dependency reaches EOL 1 year later, then the collection will EOL
+For example, if a collection has released and a dependency reaches EOL 1 year later, then the collection will EOL
 at the same time as the dependency, 1 year later.
 
+Life Cycle Phase
+================
+
+To encourage the adoption of new features while keeping the high standard of stability inherent,
+support is divided into life cycle phases; **full support** which covers the first year
+and **maintenance support** which covers the second year.
+
++--------------------------+------------------------------------+---------------------------+
+| Life Cycle Phase         | Full Support                       | Maintenance Support       |
++==========================+====================================+===========================+
+| Critical security fixes  | Yes                                | Yes                       |
++--------------------------+------------------------------------+---------------------------+
+| Bug fixes by severity    | Critical and high severity issues  | Critical severity issues  |
++--------------------------+------------------------------------+---------------------------+
+
+Severities
+==========
+
+Severity 1 (Critical):
+A problem that severely impacts your use of the software in a production environment (such as loss
+of production data or in which your production systems are not functioning). The situation halts
+your business operations and no procedural workaround exists.
+
+Severity 2 (high):
+A problem where the software is functioning but your use in a production environment is severely
+reduced. The situation is causing a high impact to portions of your business operations and no
+procedural workaround exists.
+
+Severity 3 (medium):
+A problem that involves partial, non-critical loss of use of the software in a production environment
+or development environment and your business continues to function, including by using a procedural
+workaround.
+
+Severity 4 (low):
+A general usage question, reporting of a documentation error, or recommendation for a future product
+enhancement or modification.
+
+Severities 3 and 4 are generally addressed in subsequent releases to ensure a high standard of stability
+remains available for production environments.
+
+Support Matrix
+==============
+
 These are the component versions available when the collection was made generally available (GA). The underlying
 component version is likely to change as it reaches EOL, thus components must be a version that is
 currently supported.
@@ -33,8 +77,15 @@ For IBM product lifecycle information, you can search for products using a produ
 to view IBM's `Open Enterprise SDK for Python lifecycle`_, search on product ID `5655-PYT`_, and for
 `Z Open Automation Utilities lifecycle`_, search on product ID `5698-PA1`_.
 
-Support Matrix
-==============
+The z/OS managed node includes several shells, currently the only supported shell is the z/OS Shell located in path
+`/bin/sh`_. To configure which shell the ansible control node will use on the target machine, set inventory variable
+**ansible_shell_executable**.
+
+.. code-block:: sh
+
+   ansible_shell_executable: /bin/sh
+
+
 +---------+----------------------------+---------------------------------------------------+---------------+---------------+
 | Version | Controller                 | Managed Node                                      | GA            | End of Life   |
 +=========+============================+===================================================+===============+===============+
@@ -99,4 +150,6 @@ Support Matrix
 .. _ansible-core:
    https://docs.ansible.com/ansible/latest/reference_appendices/release_and_maintenance.html#ansible-core-support-matrix
 .. _Ansible:
-   https://docs.ansible.com/ansible/latest/reference_appendices/release_and_maintenance.html#ansible-core-support-matrix
+   https://docs.ansible.com/ansible/latest/reference_appendices/release_and_maintenance.html#ansible-core-support-matrix
+.. _/bin/sh:
+   https://www.ibm.com/docs/en/zos/3.1.0?topic=descriptions-sh-invoke-shell