Allow to create release from existing branch; allow to preserve exist…

…ing `.deps` and `.build` files; improve docs (#404)

* Allow to preserve existing .deps files.

* Allow to create a PR from an existing branch.

* By default, allow to reset the .build file.

* Document some special builds that need the new options.

* Prefix branch name env var to avoid collisions with potential GitHub env vars.

* Improve option descriptions.

* Remove superfluous newline.

* Make sure that everything is correctly indented.

.github/workflows/ansible-release.yml

@@ -11,11 +11,32 @@ name: Release Ansible package
         description: >-
           Release Version. Example: 11.1.0
         required: true
+      preserve-deps:
+        description: >-
+          Whether to preserve existing `.deps` files.
+        type: boolean
+        default: false
+      allow-reset-build-deps:
+        description: >-
+          Whether to allow resetting existing `.build` files during alpha and beta-1 releases.
+
+          Should only be set to `false` for specific alpha or beta-1 releases if the deps and
+          build files have been prepared manually.
+        type: boolean
+        default: true
+      existing-branch:
+        description: >-
+          If provided, assumes that a branch of this name exists in the `ansible-build-data`
+          repository. Changes will be pushed to this branch, and the PR will be created from
+          it.
+        type: string
+        default: ''
 env:
   CI_COMMIT_MESSAGE: >-
     Ansible ${{ inputs.ansible-version }}:
     Dependencies, changelog and porting guide
   ANSIBLE_VERSION: ${{ inputs.ansible-version }}
+  ANSIBLE_BRANCH_NAME: ${{ inputs.existing-branch || ('publish-' + inputs.ansible-version) }}
 
 jobs:
   build:
@@ -38,11 +59,12 @@ jobs:
       - name: Pre-create build directory
         run: mkdir -p antsibull/build
 
-      # This is where the antsibull build-release role expects it by default
       - name: Check out ansible-build-data under antsibull build directory
         uses: actions/checkout@v4
         with:
+          # This is where the antsibull build-release role expects it by default
           path: antsibull/build/ansible-build-data
+          ref: ${{ inputs.existing-branch || '' }}
 
       - name: Set up Python 3.11
         uses: actions/setup-python@v5
@@ -83,9 +105,10 @@ jobs:
           set_output('major-version', version.major)
 
       - name: Checking out to a new branch
+        if: inputs.existing-branch == ''
         working-directory: antsibull/build/ansible-build-data
         run: |
-          git checkout -b "publish-${ANSIBLE_VERSION}"
+          git checkout -b "${ANSIBLE_BRANCH_NAME}"
 
       - name: Setting the user details
         run: |
@@ -96,13 +119,17 @@ jobs:
 
       - name: Building a release with the defaults
         working-directory: antsibull
+        env:
+          PRESERVE_DEPS: ${{ inputs.preserve-deps }}
+          ALLOW_RESET_BUILD_DEPS: ${{ inputs.allow-reset-build-deps }}
+          # Make result better readable
+          ANSIBLE_CALLBACK_RESULT_FORMAT: yaml
         run: >-
           ansible-playbook -vv playbooks/build-single-release.yaml
           -e antsibull_data_reset=false
+          -e "antsibull_build_reset=${ALLOW_RESET_BUILD_DEPS}"
           -e "antsibull_ansible_version=${ANSIBLE_VERSION}"
-        env:
-          # Make result better readable
-          ANSIBLE_CALLBACK_RESULT_FORMAT: yaml
+          -e "antsibull_preserve_deps=${PRESERVE_DEPS}"
 
       - name: Upload artifact
         uses: actions/upload-artifact@v4
@@ -115,9 +142,9 @@ jobs:
         working-directory: >-
           antsibull/build/ansible-build-data/${{ steps.extract-version.outputs.major-version }}
         run: |
-         git add .
-         git commit -m "${CI_COMMIT_MESSAGE}"
-         git push origin "publish-${ANSIBLE_VERSION}"
+          git add .
+          git commit -m "${CI_COMMIT_MESSAGE}"
+          git push origin "${ANSIBLE_BRANCH_NAME}"
 
       - name: Create PR to the ansible-build-data
         id: create-pr
@@ -130,7 +157,7 @@ jobs:
           echo -n "pr_url=" >> "${GITHUB_OUTPUT}"
           gh pr create \
           --base main \
-          --head "publish-${ANSIBLE_VERSION}" \
+          --head "${ANSIBLE_BRANCH_NAME}" \
           --title "Release Ansible ${ANSIBLE_VERSION}" \
           --body "${body}" | tee -a "$GITHUB_OUTPUT"
 

docs/automated-process.md

@@ -16,15 +16,31 @@ release process. The automated processes uses GitHub Actions to automate the
 
 1. Trigger [the automated
    workflow](https://github.com/ansible-community/ansible-build-data/actions/workflows/ansible-release.yml)
-   on the **Actions** tab of the repository and specify the release version,
-   such as `11.2.0` or `12.0.0rc1`. The process will create a PR in the
-   [`ansible-build-data` repository](https://github.com/ansible-community/ansible-build-data/).
-   Afterwards, it will wait for approval before continuing with uploading the
-   package to PyPI. All users in the [ansible-community/release-management-wg
-   group](https://github.com/orgs/ansible-community/teams/release-management-wg)[^1]
-   will be informed with a notification once the approval is needed.
-   The notification includes a link to the page where the upload step can be
-   approved.
+   on the **Actions** tab of the repository. This workflow has multiple inputs.
+   The most important is the release version, such as `11.2.0` or `12.0.0rc1`.
+   This always has to be specified.
+
+    The following additional inputs are required for special releases. Generally
+    you do not need to pass them and can rely on their defaults. Cases where you
+    need these inputs are described in the [Special builds](#special-builds)
+    section below.
+
+    * You can optionally decide whether to preserve existing `.deps` files.
+      The default is to regenerate them.
+    * You can optionally decide whether the `.build` file should be regenerated
+      during alpha and beta-1 releases.
+    * You can also specify an existing branch in the [`ansible-build-data`
+      repository](https://github.com/ansible-community/ansible-build-data/) to
+      create the PR on.
+
+    The process will create a PR in the [`ansible-build-data`
+    repository](https://github.com/ansible-community/ansible-build-data/).
+    Afterwards, it will wait for approval before continuing with uploading the
+    package to PyPI. All users in the [ansible-community/release-management-wg
+    group](https://github.com/orgs/ansible-community/teams/release-management-wg)[^1]
+    will be informed with a notification once the approval is needed.
+    The notification includes a link to the page where the upload step can be
+    approved.
 
 2. Check out the PR in your `ansible-build-data` clone and copy the updated
    porting guide from its `${MAJOR_VERSION}` directory into the
@@ -53,3 +69,69 @@ release process. The automated processes uses GitHub Actions to automate the
 
 [^1]: This group is configured as "Required reviewers" for the "Configure pypi"
       build environment in GitHub Actions of the `ansible-build-data` repository.
+
+## Special builds
+
+### Builds with a specific release summary other than the default one
+
+Sometimes you want to use a different release summary than the default one.
+For example for the Ansible 9.5.1 release, we included some text that explained
+why the release has version 9.5.1 and not 9.5.0.
+
+For this, create a new branch in `ansible-build-data`. Add a `release_summary`
+changelog entry for the new release to the `changelog.yaml` file in the major
+version's directory. Make sure to follow the same basic structure of the version's
+record in `changelog.yaml`. This can look as follows:
+```yaml
+releases:
+  ...
+  12.3.4:
+    changes:
+      release_summary: |
+        Release Date: 2024-05-14
+
+        Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`_
+
+        This is a special release because of ...
+```
+
+After that, you can start the automated workflow. You need to set the following option
+next to the release version:
+
+1. Set `existing-branch` to the branch you pushed to the `ansible-build-data`
+   repository.
+
+### Additional release candidates (rc2 etc.)
+
+For these release candidates, you only want to bump very specific collection
+versions, and not use new bugfix releases of potentially all included collections.
+
+For this, create a new branch in `ansible-build-data` where you copy the `.deps`
+file of the previous release candidate to the location of the `.deps` file of the
+planned release. Then you modify the new `.deps` file with the version updates
+you plan to make.
+
+After that, you can start the automated workflow. You need to set the following options
+next to the release version:
+
+1. Set `preserve-deps` to `true`;
+
+2. Set `existing-branch` to the branch you pushed to the `ansible-build-data`
+   repository.
+
+### New major release (x.0.0)
+
+The new major release should include exactly the same dependencies as the last
+release candidate.
+
+For this, create a new branch in `ansible-build-data` where you copy the `.deps`
+file of the last release candidate to the location of the `.deps` file of the
+planned major release. Do not modify the new `.deps` file with any version updates.
+
+After that, you can start the automated workflow. You need to set the following options
+next to the release version:
+
+1. Set `preserve-deps` to `true`;
+
+2. Set `existing-branch` to the branch you pushed to the `ansible-build-data`
+   repository.