diff --git a/docs/release-process.md b/docs/release-process.md new file mode 100644 index 0000000000..bb916d5803 --- /dev/null +++ b/docs/release-process.md @@ -0,0 +1,156 @@ +# Ansible Release Process + +## Preamble + +This document describes the ansible community package release process. + +> **Note** +> +> Throughout this page, placeholder values in code blocks are formatted as +> `{PLACEHOLDER}` where `PLACEHOLDER` 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`][container] +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 repository clones. +This only needs to be done once. + +1. [Fork][abd-fork] the [ansible-build-data] repository. +2. Checkout the antsibull and ansible-documentation repositories + and change into antsibull. + + ``` + git clone https://github.com/ansible/ansible-documentation + git clone https://github.com/ansible-community/antsibull + cd antsibull + ``` +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 {USERNAME} https://github.com/{USERNAME}/ansible-build-data + git fetch {USERNAME} -v + ``` + +## Preform release process + +1. Change into the antsibull 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`, `ansible-core`, and `twine` python packages, + as well as the community.general collection. + + ``` + python3 -m pip install antsibull ansible-core twine + ansible-galaxy collection install --force community.general + ``` + +3. Run the [ansible release playbook][release-playbook] + with the appropriate options. + You can see the [argument spec][release-playbook-args] + 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][tagging-enforcement] 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 {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 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 Matrix and the mailing list. + TODO: Move announcement templates into this repository. + Release managers can copy and paste the previous release's announcement for + now. + Make sure to change the version numbers and sha256sum in the announcement + text. + +[container]: https://hub.docker.com/_/python +[abd-fork]: https://github.com/ansible-community/ansible-build-data/fork +[ansible-build-data]: https://github.com/ansible-community/ansible-build-data +[release-playbook]: https://github.com/ansible-community/antsibull/blob/main/playbooks/build-single-release.yaml +[release-playbook-args]: https://github.com/ansible-community/antsibull/blob/main/roles/build-release/meta/argument_specs.yml +[tagging-enforcement]: https://github.com/gotmax23/ansible-build-data/blob/docs/docs/policies.md#enforcement