[Release][1.9.4] Release tasks

[fernandofloresg]

Release new version 1.9.4 with #1780 changes in place.

Release Requirements Checklist

This checklist is a chronological ordering of the release tasks to complete for an IBM Ansible z/OS core collection. This template is for a GA release that will release to Ansible Automation Platform and Galaxy as well. If you are following this issue, note that the version number is subject to change based on the certification outcome.

By this point the stagging-v<version> had been code frozen and releases tasks must only be meta data related, for example, updating galaxy.yml, runtime.yml, generating module doc if needed, release notes etc.

You should be checking off each task as it completes.

General workflow

This a subsequent release (not a patch) thus these releases tasks will eventually be merged intomain and into dev to allow for the meta data updates to propagate as well as the release tag.

(1) Technical Writer Tasks

• Ensure all technical writer Git issues are resolved for this release

(2) Release Tasks for release-tasks-v<version> branch:

• Update galaxy.yml
• Update meta/runtime.yml
• Update meta/ibm_zos_core_meta.yml
• Update README.md
• Update .ansible-lint config such that galaxy.yml and build_ignore entries are in sync.
• Review copyrights are updated as needed, e.g. current year if changes are made
• Update the support matrix in docs/resources/releases_maintenance.rst to add the newest entry and the correct support dates & supported dependencies version for the release.
• Generate module docs (restructured text - RST) and check it into the release branch
• Add a change log summary fragment in the /changelog directory for this release:
  - Create a file called "v<major>.<minor>.<patch>_summary.yml", eg v1.6.0_summary.yml
  - Place it under ibm_zos_core/changelogs/fragments/
  - Add contents (update the date, don't go past the current day):

release_summary: |
  Release Date: '2023-06-23'
  This changelog describes all changes made to the modules and plugins included
  in this collection. The release date is the date the changelog is created.
  For additional details such as required dependencies and availability review
  the collections `release notes <https://ibm.github.io/z_ansible_collections_doc/ibm_zos_core/docs/source/release_notes.html>`__

• Generate CHANGELOG.rst
  • antsibull-changelog lint
  • antsibull-changelog release or antsibull-changelog release -v
• Create release notes (docs/source/release_notes.rst)
• Run markdown linter pymarkdownlnt scan README.md
• Review all module source imports; ensure sure no new imports are subject to license discrepancies

(3) Quality assurance

• Run a Mend scan and check the results into the designated repository

  • Note: Doing this on the release-tasks-v<version> branch provides opportunity to make last minute changes if needed.

• Run a Bandit scan and check the results into the designated repository

• Ansible-lint validation , manual step at the moment, choose from one of the below to run ansible-lint:

  • ./ac --ac-lint
  • ./ac --venv-start
    • ansible-lint -c .ansible-lint --profile production

• Sanity tests, use the pipeline option and choose to run only the sanity tests by checking ANSIBLE_TEST_ONLY which specifies only Ansible Certification tests and security scan run, meaning no functional tests run." As a backup option, you can use the ./ac tool with similar options ./ac --ac-sanity --version 3.10 to run sanity.

• Run the galaxy importer (currently a manual step as its not part of the pipeline yet)

  • python -m galaxy_importer.main ibm-ibm_zos_core-<version>.tar.gz. You can perform this with commands:

    $ ./ac --venv-start
    $ python -m galaxy_importer.main ibm-ibm_zos_core-1.7.0.tar.gz
    

  • Check output log for any errors/issues. For success, look for the following msg:

     Collection loading complete
     Importer processing completed successfully
    

• Full pipeline regression at 100% success on either release-tasks-v<version> or stagging-v<version>:

  • Certify on IBM Enterprise Python versions 3.11 or latest (with the latest PTF for env var PYTHONSTDINENCODING)
  • Certify on IBM Enterprise Python and new environment var PYTHONSTDINENCODING
  • Certify on ZOAU 1.3.0
  • Certify on ansible-core v2.15.x or latest supported by Ansible Automation Platform
  • Ensure RUN_ALL_TESTS is selected

(5) Validation

• Build the image from staging-v<version> branch, unpack it up, inspect the contents. Ensure only the required files are contained in the package.
• Test collection quality with an upload to the IBM HCF development Galaxy Server by uploading the build from branch staging-v<version>. This first build test is to alert you to any issues that might need to be made before opening a pull request.

(6) GitHub

• Open a pull request for staging-v<version> against main.
• When the pull request has been approved, do not merge it, build the collection again and test the collection quality again with a new build from the reviewed staging-v<version> branch by uploading it to the Ansible development Galaxy Server. (Do not merge the pull request till after AAP and Galaxy success.)

(7) Release tasks (In this order)

• Upload to AAP, on success continue to the next step.
• Upload to Galaxy, on success continue to the next step.
• Merge pull request for staging-v<version> against main and DO NOT delete the staging-v<version> branch, you will need the staging-v<version> branch soon enough.
• Create a draft release in GitHub, for:
  • "Choose a tag", enter v<version>, eg v1.6.0
  • "Target" , enter main
  • "Release title" , enter release-v<version>, eg release-v1.6.0
  • "Describe this release", enter the contents created for doc/source/release_notes.rst, you may need to remove trailing _ from the RST you paste since the description is supposed to be Markdown.
• Publish the Github release draft, include the collection archive as part of the release.
• Open a Git issue in z_ansible_collections_doc to have Red Hat® Ansible Certified Content for IBM Z docs generated
• Push stagging-v<version> changes into dev to ensure any fixes and meta are propagated upstream. There are different ways to do this, I find a merge ends up complicating things because dev will have received an entire quarters of changes and now old changes are pushed upstream. Generally, when performing the release tasks from bullet (2), I commit each separately so that I can cherry pick them later.All that should change is metadata , eg galaxy.yml , release_notes.rst, etc, no source. In case there is a source change, separate commits makes it easy to cherry pick. Optionally (usually what i do), you can cherry pick the PR which will have by default squashed all the individual commits. For example, if you want to cherry-pick the squashed PR, get the commit id from the PR then perform the following commands:

  git checkout dev <-- check out dev since this is where we want to cherry-pick to
  git pull                 <-- pull the latest
  git checkout -b cherry-picked-170-into-dev <-- create a new branch
  git cherry-pick 472611  <-- cherry-pick the squashed PR 
  git push -u origin cherry-picked-170-into-dev <-- push the changes and then open a PR against dev
  

(8) Log collection

• Copy any additional playbook or manual tests performed into the release folder
• Copy the pipeline log from Jenkins into the release folder
• Copy the Automation Hub import log into the release folder
• Copy the Galaxy import log in the release folder
• Copy the git log (git log --pretty=oneline) into the release folder

[gundalow]

Hi,
I'm part of the Ansible Partner Team at Red Hat.
It looks like 1.9.4 go published to Automation Hub within the past day. Given the (7) Release tasks section above, was this done by mistake?

FYI @epacific1 @anweshadas

[fernandofloresg]

Hi @gundalow, it is not a mistake. Is there an issue with it?

If you are asking because of ansible-lint errors on upload, the version 1.9.x was out before ansible-lint and galaxy-importer had been updated, it was agreed that we would not make the large back ports to address these issues, such issues are fixed in v1.10.0 or later.

[gundalow]

Just checking as we'd seen v1.11 (2 months ago) as the previous release in Hub.
1.9.4 (1 day ago)
1.9.3 (24 days ago)
1.9.2 (3 months ago)

So it looks like you are releasing the 1.9.x series AND a newer version at the same time.

That's fine, just wanted to check which release should appear on Catalogue

Is it right that you have pushed a release before it's been tagged?

We just wanted to check as the previous release in Hub was

[fernandofloresg]

Yes that is correct. We provide support to each version after is made generally available (GA) up to two years unless a dependency reaches EOL prior to the 2 years, for 1.9.x we still have 5 months of support, but we don't expect any further patches unless is a critical issue.

We will release both v1.11.1 and v1.12.0 soon too, the release displayed on catalogue should be the greatest, at least for this collection. So is ok to keep v1.11.0.

Release is tagged in GitHub after the release has been uploaded to AAP and Galaxy, that is the next step in the release process actually, so I will do that today.

Thanks for reaching out.