New Ansible Releases and Freezes

Preamble

Releasing new Ansible major versions and frozen releases requires some special handling. For information about the general release process, see Ansible Release Process.

Setting up for a new major release

After the release of X.0.0, it is necessary to create the directory structure for Ansible X+1.

1. Determine the current major version and next major version

   CURRENT_MAJOR_VERSION=9
   NEXT_MAJOR_VERSION=10
   

2. Create the major version directory

   mkdir "${NEXT_MAJOR_VERSION}/"
   

3. Copy over the ansible.in and collection-meta.yaml files

   cp "${CURRENT_MAJOR_VERSION}/ansible.in" "${CURRENT_MAJOR_VERSION}/collection-meta.yaml" \
      "${NEXT_MAJOR_VERSION}/"
   

4. Symlink ${CURRENT_MAJOR_VERSION}.0.0's deps file to ${NEXT_MAJOR_VERSION}/ancestor.deps

   ln -sr "${CURRENT_MAJOR_VERSION}/ansible-${CURRENT_MAJOR_VERSION}.0.0.deps" \
      "${NEXT_MAJOR_VERSION}/ancestor.deps"
   

5. Create a stub changelog.yaml file

   cat <<EOF >${NEXT_MAJOR_VERSION}/changelog.yaml
   ---
   ancestor: ${CURRENT_MAJOR_VERSION}.0.0
   releases: {}
   EOF
   

6. Create a blank validate-tags-ignores file

   touch "${NEXT_MAJOR_VERSION}/validate-tags-ignores"
   

7. Add the next major version to ansible-build-data's CI

   Open .github/workflows/antsibull-build.yml and the following block to the matrix:

   - name: Ansible ${NEXT_MAJOR_VERSION}
     ansible_version: ${NEXT_MAJOR_VERSION}.99.0
     ansible_major_version: ${NEXT_MAJOR_VERSION}
   

8. Commit the changes

   git add "${NEXT_MAJOR_VERSION}" .github/workflows/antsibull-build.yml
   

9. Submit a PR against ansible-build-data

Freeze release

Beyond the regular Ansible Release Process, X.Y.0 releases require special handling before running the release playbook.

1. Determine the previous and the current releases

   MAJOR_VERSION=9
   VERSION=9.0.0
   PREVIOUS_VERSION=9.0.0rc1
   

2. Set up your Git clones and release venv as outlined in the Ansible Release Process document.

3. Copy over the previous release's deps and galaxy files.

   cp "ansible-${PREVIOUS_VERSION}.yaml" "ansible-${VERSION}.yaml"
   cp "ansible-${PREVIOUS_VERSION}.deps" "ansible-${VERSION}.deps"
   

4. Edit the current ansible version in the deps file

   sed -i "s|^_ansible_version:.*$|_ansible_version: ${VERSION}|" \
      "ansible-${VERSION}.deps"
   

5. Add a changelog entry for the new release

   Open ${MAJOR_VERSION}/changelog.yaml and the following block to the releases table:

     ${VERSION}:
       changes:
         release_summary: 'Release Date: ${RELEASE_DATE}
   
   
           `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`_'
       release_date: '${RELEASE_DATE}'
   

   The release date should be formatted as YYYY-MM-DD.

6. Manually update specific collection versions if needed.

   In some cases, it may be necessary to update certain collections if, for example, a serious bug is found is one of the collections. In that case, open up the deps and galaxy files copied over in the step 2 and change the versions for the collections in question. Make sure that the versions in both files are consistent.

7. Generate the tags data file

   antsibull-build validate-tags \
       --data-dir . \
       --ignores-file validate-tags-ignores \
       --output "ansible-${VERSION}-tags.yaml" \
       "${VERSION}"
   

8. Run the the release playbook as outlined in Ansible Release Process. Make sure to use pass -e antsibull_data_reset=false to preserve the ansible-build-data modifications.