Document the automated release process (#381)

* Document announcement automation.

* Add basic docs for automated release process.

* Update formulation.

* Make link clickable.

* Add warning on PR / approval order.

* Make sure the indent is right.

* Address Alicia's comments.

* Address Don's comments.

Co-authored-by: Don Naro <[email protected]>

* Split sentence.

* Implement gotmax's suggestions.

Co-authored-by: Maxwell G <[email protected]>

* Line length breaks.

* Use right directory.

* Simplify input.

* Update who is notified.

---------

Co-authored-by: Don Naro <[email protected]>
Co-authored-by: Maxwell G <[email protected]>

Author: 3 people

docs/automated-process.md

@@ -0,0 +1,55 @@
+# How to release a new version of the Ansible Community Package — Automated Release Process
+
+## Preamble
+
+This document describes the (mostly) automated ansible community package
+release process. The automated processes uses GitHub Actions to automate the
+[manual release process](release-process.md).
+
+!!! note
+    Throughout this page, placeholder values in code blocks are formatted as
+    `${PLACEHOLDER_VALUE}` where `PLACEHOLDER_VALUE` describes the value to
+    specify.
+
+
+## Trigger the workflow
+
+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.
+
+2. Check out the PR in your `ansible-build-data` clone and copy the updated
+   porting guide from its `${MAJOR_VERSION}` directory into the
+   [`docs/docsite/rst/porting_guides/`](https://github.com/ansible/ansible-documentation/tree/devel/docs/docsite/rst/porting_guides/)
+   directory of the [`ansible-documentation`
+   repository](https://github.com/ansible/ansible-documentation/). Create a
+   PR for updating the porting guide for the `devel` branch of
+   `ansible-documentation`.
+
+3. After both PRs (in `ansible-build-data` and `ansible-documentation`) are
+   approved, merge the `ansible-build-data` PR and approve the next workflow
+   step (**in this order!** the next steps of the workflow require the PR to be
+   merged!). This will upload the package to PyPI and tag the release in
+   `ansible-build-data`.
+
+4. Merge the porting guide PR, and backport it to the latest `stable-x`
+   branches down to the ansible-core version that is included in the Ansible
+   release.
+
+5. Announce the release on the Forum, Matrix, and the mailing list by running
+   the following command in the `${MAJOR_VERSION}` directory of the
+   `ansible-build-data` checkout:
+    ```
+    antsibull-build announcements --send --data-dir . ${VERSION}
+    ```
+
+[^1]: This group is configured as "Required reviewers" for the "Configure pypi"
+      build environment in GitHub Actions of the `ansible-build-data` repository.

docs/release-process.md

@@ -1,8 +1,10 @@
-# Ansible Release Process
+# How to release a new version of the Ansible Community Package — Manual Release Process
 
 ## Preamble
 
-This document describes the ansible community package release process.
+This document describes the "manual" ansible community package release process.
+There exists an [automated version of this process](automated-process.md) using
+GitHub Actions.
 
 !!! note
     Throughout this page, placeholder values in code blocks are formatted as
@@ -92,9 +94,10 @@ This only needs to be done once.
 
     !!! 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.
+        `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.
 
@@ -110,9 +113,9 @@ This only needs to be done once.
 
     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
+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/
@@ -141,12 +144,12 @@ This only needs to be done once.
     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.
+8. Announce the release on the Forum, Matrix, and the mailing list by running
+   the following command in the `${MAJOR_VERSION}` directory of the
+   `ansible-build-data` checkout:
+    ```
+    antsibull-build announcements --send --data-dir . ${VERSION}
+    ```
 
 [container]: https://hub.docker.com/_/python
 [abd-fork]: https://github.com/ansible-community/ansible-build-data/fork

mkdocs.yml

@@ -18,6 +18,7 @@ copyright: >
 markdown_extensions:
   # Builtin
   - admonition
+  - footnotes
   - toc:
       permalink: true
   # pymdownx
@@ -26,6 +27,7 @@ markdown_extensions:
   - pymdownx.superfences
 nav:
   - Ansible Build Data: README.md
-  - release-process.md
+  - Automated Ansible Release Process: automated-process.md
+  - Manual Ansible Release Process: release-process.md
   - policies.md
   - new-ansible-and-freezes.md