Skip to content

Latest commit

 

History

History
167 lines (125 loc) · 5.72 KB

release-process.md

File metadata and controls

167 lines (125 loc) · 5.72 KB
Raw

How to release a new version of the Ansible Community Package — Manual Release Process

Preamble

This document describes the "manual" ansible community package release process. There exists an automated version of this process using GitHub Actions.

!!! note Throughout this page, placeholder values in code blocks are formatted as ${PLACEHOLDER_VALUE} where PLACEHOLDER_VALUE describes the value to fill in.

Set up container

Release managers may choose to preform the following steps inside a podman or docker container created from the docker.io/library/python:3.10 image. Make sure to mount your working directory as a volume so you don't have to set up new repository clones every time.

podman run --name ansible-release -v ${PERSISTENT_DIRECTORY}:/pwd:z -w /pwd -ti docker.io/library/python:3.10 bash

Set up repository clones

First, you need to set up ansible-build-data and antsibull-build repository clones. This only needs to be done once.

  1. Fork the ansible-build-data repository.

  2. Checkout the antsibull-build and ansible-documentation repositories and change into antsibull-build.

    git clone https://github.com/ansible/ansible-documentation
git clone https://github.com/ansible-community/antsibull-build
cd antsibull-build

  3. Checkout ansible-build-data and configure your fork.

    To checkout the repository run

    mkdir build
cd build
git clone https://github.com/ansible-community/ansible-build-data
cd ansible-build-data

    Then, configure your fork. This guide uses your Github username as the fork remote name.

    git remote add ${GH_USERNAME} https://github.com/${GH_USERNAME}/ansible-build-data
git fetch ${GH_USERNAME} -v

Perform release process

  1. Change into the antsibull-build checkout. Make sure you have the main branch checked out and run git pull to update to the latest commit.

  2. Create a clean virtual environment for the release process.

    rm -rf release-venv
python3 -m venv release-venv
. ./release-venv/bin/activate
python3 -m pip install -U pip

    Install the antsibull-build, ansible-core, and twine python packages, as well as the community.general collection.

    python3 -m pip install antsibull-build ansible-core twine
ansible-galaxy collection install --force community.general

  3. Run the ansible release playbook with the appropriate options. You can see the argument spec for a full breakdown, but this describes the basic usage.

    export ANSIBLE_CALLBACK_RESULT_FORMAT=yaml
ansible-playbook playbooks/build-single-release.yaml -e antsibull_ansible_version=${VERSION}

    !!! note When building ansible versions greater than 9.0.0a1, Validate tags file task failures will fail the release playbook instead of warning and moving on. See policies.md for how to proceed if this step fails.

  4. Commit the changes and push them to your fork.

    You can run the following commands to do so

    cd build/ansible-build-data
git switch -c release-${VERSION}
git add ${MAJOR_VERSION}/
git commit -m "Ansible ${VERSION}: Dependencies, changelog and porting guide"
git push -u ${GH_USERNAME} release-${VERSION}

    Then, submit a pull request against ansible-build-data upstream.

  5. Submit a PR to ansible/ansible-documentation to add the new porting guide to the docsite. Copy the porting guide to the ansible docsite directory in your ansible checkout with the following command

    cp ${MAJOR_VERSION}/porting_guide_${MAJOR_VERSION}.rst ../ansible-documentation/docs/docsite/rst/porting_guides/

    switch to the ansible checkout, commit and push the changes, and then submit a PR as you normally would. You can use Add Ansible community ${VERSION} porting guide as the commit message.

  6. Once the ansible-build-data PR has been merged, publish the build artifacts to PyPI. From the antsibull-build repository root, run

    twine upload build/ansible-${VERSION}.tar.gz build/ansible-${VERSION}*.whl

  7. Tag the release commit in the ansible-build-data repository.

    cd build/ansible-build-data
git switch main
git pull
git tag ${VERSION} ${MERGED_PR_COMMIT_HASH} -a -m "Ansible ${VERSION}: Changelog, Porting Guide and Dependent Collection Details"
git push --follow-tags

  8. Announce the release on the Forum and Matrix by running the following command in the ${MAJOR_VERSION} directory of the ansible-build-data checkout:

    antsibull-build announcements --send --data-dir . ${VERSION} [ --end-of-life ]

    The --end-of-life flag should be added if this is the final release for the ${MAJOR_VERSION} major release train.

    This will open your default browser to do the announcement on the forum. It will also tell you where to announce this on Matrix, ask for the URL of the forum thread, and create a suitable text in your clipboard that you can copy to Matrix.