From 8b99bf9f4d6158d2dc12895a0d7c2f475843cc2b Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Sun, 12 Nov 2023 21:43:12 +0000 Subject: [PATCH 1/3] docs: add new-ansible-and-freezes documentation --- docs/new-ansible-and-freezes.md | 149 ++++++++++++++++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 docs/new-ansible-and-freezes.md diff --git a/docs/new-ansible-and-freezes.md b/docs/new-ansible-and-freezes.md new file mode 100644 index 0000000000..1dbfbdad31 --- /dev/null +++ b/docs/new-ansible-and-freezes.md @@ -0,0 +1,149 @@ +# 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](release-process.md). + +## 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 previous major version + + ``` sh + CURRENT_MAJOR_VERSION=9 + NEXT_MAJOR_VERSION=10 + ``` + +2. Create the major version directory + + ``` sh + mkdir "${NEXT_MAJOR_VERSION}/" + ``` + +3. Copy over the `ansible.in` and `collection-meta.yaml` files + + ``` sh + 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` + + ``` sh + ln -sr "${CURRENT_MAJOR_VERSION}/${CURRENT_MAJOR_VERSION}.0.0.deps" \ + "${NEXT_MAJOR_VERSION}/ancestor.deps" + ``` + +5. Create a stub `changelog.yaml` file + + ``` sh + cat <${NEXT_MAJOR_VERSION}/changelog.yaml + --- + ancestor: ${CURRENT_MAJOR_VERSION}.0.0 + releases: {} + EOF + ``` + +6. Create a blank `validate-tags-ignores` file + + ``` sh + 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: + + ``` yaml + - name: Ansible ${NEXT_MAJOR_VERSION} + ansible_version: ${NEXT_MAJOR_VERSION}.99.0 + ansible_major_version: ${NEXT_MAJOR_VERSION} + ``` + +8. Commit the changes + + ``` sh + 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](release-process.md), X.Y.0 +releases require special handling before running the release playbook. + +1. Determine the previous and the current releases + + ``` sh + 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](release-process.md) document. + +3. Copy over the previous release's deps and galaxy files. + + ``` sh + 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 + + ``` sh + 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: + + ``` yaml + ${VERSION}: + changes: + release_summary: 'Release Date: ${RELEASE_DATE} + `Porting Guide `_' + 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 + + ``` sh + 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](release-process.md). + Make sure to use pass `-e antsibull_data_reset=false` to preserve the + ansible-build-data modifications. From 80e395bab6269d8ccc2477ab780621b30da93284 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Sun, 19 Nov 2023 13:43:59 -0600 Subject: [PATCH 2/3] docs/new-ansible-and-freezes.md: properly refer to major verions Co-authored-by: Felix Fontein --- docs/new-ansible-and-freezes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/new-ansible-and-freezes.md b/docs/new-ansible-and-freezes.md index 1dbfbdad31..2d51da5b7e 100644 --- a/docs/new-ansible-and-freezes.md +++ b/docs/new-ansible-and-freezes.md @@ -14,7 +14,7 @@ see [Ansible Release Process](release-process.md). 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 previous major version +1. Determine the current major version and next major version ``` sh CURRENT_MAJOR_VERSION=9 From a15d287cd4634a8021871ff9df23e026e47bf7ea Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Sun, 19 Nov 2023 13:44:17 -0600 Subject: [PATCH 3/3] docs/new-ansible-and-freezes.md: fix deps file path Co-authored-by: Felix Fontein --- docs/new-ansible-and-freezes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/new-ansible-and-freezes.md b/docs/new-ansible-and-freezes.md index 2d51da5b7e..5921961a5f 100644 --- a/docs/new-ansible-and-freezes.md +++ b/docs/new-ansible-and-freezes.md @@ -38,7 +38,7 @@ structure for Ansible `X+1`. `${NEXT_MAJOR_VERSION}/ancestor.deps` ``` sh - ln -sr "${CURRENT_MAJOR_VERSION}/${CURRENT_MAJOR_VERSION}.0.0.deps" \ + ln -sr "${CURRENT_MAJOR_VERSION}/ansible-${CURRENT_MAJOR_VERSION}.0.0.deps" \ "${NEXT_MAJOR_VERSION}/ancestor.deps" ```