chore: automate release process (#1394)

Author: WilliamBergamin

.github/maintainers_guide.md

@@ -10,14 +10,14 @@ this project. If you use this package within your own software as is but don't p
 
 We recommend using [pyenv](https://github.com/pyenv/pyenv) for Python runtime management. If you use macOS, follow the following steps:
 
-```bash
-$ brew update
-$ brew install pyenv
+```sh
+brew update
+brew install pyenv
 ```
 
 Install necessary Python runtimes for development/testing. You can rely on GitHub Actions workflows for testing with various major versions. <https://github.com/slackapi/bolt-python/tree/main/.github/workflows>
 
-```bash
+```sh
 $ pyenv install -l | grep -v "-e[conda|stackless|pypy]"
 
 $ pyenv install 3.8.5 # select the latest patch version
@@ -34,9 +34,9 @@ $ pyenv rehash
 
 Then, you can create a new Virtual Environment this way:
 
-```bash
-$ python -m venv env_3.8.5
-$ source env_3.8.5/bin/activate
+```sh
+python -m venv env_3.8.5
+source env_3.8.5/bin/activate
 ```
 
 ## Tasks
@@ -49,27 +49,27 @@ If you make some changes to this SDK, please write corresponding unit tests as m
 
 If this is your first time to run tests, although it may take a bit long time, running the following script is the easiest.
 
-```bash
-$ ./scripts/install_all_and_run_tests.sh
+```sh
+./scripts/install_all_and_run_tests.sh
 ```
 
 Once you installed all the required dependencies, you can use the following one.
 
-```bash
-$ ./scripts/run_tests.sh
+```sh
+./scripts/run_tests.sh
 ```
 
 Also, you can run a single test this way.
 
-```bash
-$ ./scripts/run_tests.sh tests/scenario_tests/test_app.py
+```sh
+./scripts/run_tests.sh tests/scenario_tests/test_app.py
 ```
 
 #### Run the Samples
 
 If you make changes to `slack_bolt/adapter/*`, please verify if it surely works by running the apps under `examples` directory.
 
-```bash
+```sh
 # Install all optional dependencies
 $ pip install -r requirements/adapter.txt
 $ pip install -r requirements/adapter_testing.txt
@@ -97,121 +97,123 @@ If you want to test the package locally you can.
 
 1. Build the package locally
    - Run
-     ```bash
+     ```sh
      scripts/build_pypi_package.sh
      ```
    - This will create a `.whl` file in the `./dist` folder
 2. Use the built package
    - Example `/dist/slack_bolt-1.2.3-py2.py3-none-any.whl` was created
    - From anywhere on your machine you can install this package to a project with
-     ```bash
+     ```sh
      pip install <project path>/dist/slack_bolt-1.2.3-py2.py3-none-any.whl
      ```
    - It is also possible to include `slack_bolt @ file:///<project path>/dist/slack_bolt-1.2.3-py2.py3-none-any.whl` in a [requirements.txt](https://pip.pypa.io/en/stable/user_guide/#requirements-files) file
 
-### Releasing
-
-#### Generate API reference documents
+### Generate API reference documents
 
-```bash
+```sh
 ./scripts/generate_api_docs.sh
 ```
 
+### Releasing
+
 #### test.pypi.org deployment
 
-##### $HOME/.pypirc
+[TestPyPI](https://test.pypi.org/) is a separate instance of the Python Package
+Index that allows you to try distribution tools and processes without affecting
+the real index. This is particularly useful when making changes related to the
+package configuration itself, for example, modifications to the `pyproject.toml` file.
+
+You can deploy this project to TestPyPI using GitHub Actions.
 
-```toml
-[testpypi]
-username: {your username}
-password: {your password}
+To deploy using GitHub Actions:
+
+1. Push your changes to a branch or tag
+2. Navigate to <https://github.com/slackapi/bolt-python/actions/workflows/pypi-release.yml>
+3. Click on "Run workflow"
+4. Select your branch or tag from the dropdown
+5. Click "Run workflow" to build and deploy your branch to TestPyPI
+
+Alternatively, you can deploy from your local machine with:
+
+```sh
+./scripts/deploy_to_test_pypi.sh
 ```
 
 #### Development Deployment
 
-1. Create a branch in which the development release will live:
-    - Bump the version number in adherence to [Semantic Versioning](http://semver.org/) and [Developmental Release](https://peps.python.org/pep-0440/#developmental-releases) in `slack_bolt/version.py`
-      - Example the current version is `1.2.3` a proper development bump would be `1.3.0.dev0`
+Deploying a new version of this library to PyPI is triggered by publishing a GitHub Release.
+Before creating a new release, ensure that everything on a stable branch has
+landed, then [run the tests](#run-all-the-unit-tests).
+
+1. Create the commit for the release
+   1. In `slack_bolt/version.py` bump the version number in adherence to [Semantic Versioning](http://semver.org/) and [Developmental Release](https://peps.python.org/pep-0440/#developmental-releases).
+      - Example: if the current version is `1.2.3`, a proper development bump would be `1.2.4.dev0`
       - `.dev` will indicate to pip that this is a [Development Release](https://peps.python.org/pep-0440/#developmental-releases)
-      - Note that the `dev` version can be bumped in development releases: `1.3.0.dev0` -> `1.3.0.dev1`
-    - Commit with a message including the new version number. For example `1.3.0.dev0` & Push the commit to a branch where the development release will live (create it if it does not exist)
-      - `git checkout -b future-release`
-      - `git commit -m 'version 1.3.0.dev0'`
-      - `git push future-release`
-    - Create a git tag for the release. For example `git tag v1.3.0.dev0`.
-    - Push the tag up to github with `git push origin --tags`
-
-2. Distribute the release
-   - Use the latest stable Python runtime
-   - `python -m venv .venv`
-   - `./scripts/deploy_to_pypi_org.sh`
-   - You do not need to create a GitHub release
-
-3. (Slack Internal) Communicate the release internally
+      - Note that the `dev` version can be bumped in development releases: `1.2.4.dev0` -> `1.2.4.dev1`
+   2. Build the docs with `./scripts/generate_api_docs.sh`.
+   3. Commit with a message including the new version number. For example `1.2.4.dev0` & push the commit to a branch where the development release will live (create it if it does not exist)
+      1. `git checkout -b future-release`
+      2. `git commit -m 'chore(release): version 1.2.4.dev0'`
+      3. `git push -u origin future-release`
+2. Create a new GitHub Release
+   1. Navigate to the [Releases page](https://github.com/slackapi/bolt-python/releases).
+   2. Click the "Draft a new release" button.
+   3. Set the "Target" to the feature branch with the development changes.
+   4. Click "Tag: Select tag"
+   5. Input a new tag name manually. The tag name must match the version in `slack_bolt/version.py` prefixed with "v" (e.g., if version is `1.2.4.dev0`, enter `v1.2.4.dev0`)
+   6. Click the "Create a new tag" button. This won't create your tag immediately.
+   7. Click the "Generate release notes" button.
+   8. The release name should match the tag name!
+   9. Edit the resulting notes to ensure they have decent messaging that is understandable by non-contributors, but each commit should still have its own line.
+   10. Set this release as a pre-release.
+   11. Publish the release by clicking the "Publish release" button!
+3. Navigate to the [release workflow run](https://github.com/slackapi/bolt-python/actions/workflows/pypi-release.yml). You will need to approve the deployment!
+4. After a few minutes, the corresponding version will be available on <https://pypi.org/project/slack-bolt>.
+5. (Slack Internal) Communicate the release internally
 
 #### Production Deployment
 
-1. Create the commit for the release:
-   - Bump the version number in adherence to [Semantic Versioning](http://semver.org/) in `slack_bolt/version.py`
-   - Build the docs with `./scripts/generate_api_docs.sh`.
-   - Commit with a message including the new version number. For example `1.2.3` & Push the commit to a branch and create a PR to sanity check.
-     - `git checkout -b v1.2.3`
-     - `git commit -a -m 'version 1.2.3'`
-     - `git push -u origin HEAD`
-   - Open a PR and merge after receiving at least one approval from other maintainers.
-
-2. Distribute the release
-   - Use the latest stable Python runtime
-      - `git checkout main && git pull`
-      - `python --version`
-      - `python -m venv .venv`
-      - `./scripts/deploy_to_pypi_org.sh`
-   - Create a new GitHub Release from the [Releases page](https://github.com/slackapi/bolt-python/releases) by clicking the "Draft a new release" button.
-      - Enter the new version number updated from the commit (e.g. `v1.2.3`) into the "Choose a tag" input.
-      - Ensure the tag `Target` branch is `main` (e.g `Target:main`).
-      - Click the "Create a new tag: x.x.x on publish" button. This won't create your tag immediately.
-      - Name the release after the version number updated from the commit (e.g. `version 1.2.3`)
-      - Auto-generate the release notes by clicking the "Auto-generate release
-      notes" button. This will pull in changes that will be included in your
-      release.
-      - Edit the resulting notes to ensure they have decent messaging that are
-      understandable by non-contributors, but each commit should still have it's
-      own line.
-      - Ensure that this version adheres to [semantic versioning](http://semver.org/). See
-      [Versioning](#versioning-and-tags) for correct version format. Version tags
-      should match the following pattern: `v2.5.0`.
-
-   ```markdown
-   ## New Features
-
-   ### Awesome Feature 1
-
-   Description here.
-
-   ### Awesome Feature 2
-
-   Description here.
-
-   ## Changes
-
-   * #123 Make it better - thanks @SlackHQ
-   * #123 Fix something wrong - thanks @seratch
-   ```
-
-3. (Slack Internal) Communicate the release internally
-   - Include a link to the GitHub release
-
-4. Make announcements
-   - #tools-bolt in community.slack.com
-
-5. (Slack Internal) Tweet by @SlackAPI
-   - Not necessary for patch updates, might be needed for minor updates, definitely needed for major updates. Include a link to the GitHub release
+Deploying a new version of this library to PyPI is triggered by publishing a GitHub Release.
+Before creating a new release, ensure that everything on the `main` branch since
+the last tag is in a releasable state! At a minimum, [run the tests](#run-all-the-unit-tests).
+
+1. Create the commit for the release
+   1. In `slack_bolt/version.py` bump the version number in adherence to [Semantic Versioning](http://semver.org/) and the [Versioning](#versioning-and-tags) section.
+   2. Build the docs with `./scripts/generate_api_docs.sh`.
+   3. Commit with a message including the new version number. For example `1.2.3` & push the commit to a branch and create a PR to sanity check.
+      1. `git checkout -b 1.2.3-release`
+      2. `git commit -m 'chore(release): version 1.2.3'`
+      3. `git push -u origin 1.2.3-release`
+   4. Add relevant labels to the PR and add the PR to a GitHub Milestone.
+   5. Merge in release PR after getting an approval from at least one maintainer.
+2. Create a new GitHub Release
+   1. Navigate to the [Releases page](https://github.com/slackapi/bolt-python/releases).
+   2. Click the "Draft a new release" button.
+   3. Set the "Target" to the `main` branch.
+   4. Click "Tag: Select tag"
+   5. Input a new tag name manually. The tag name must match the version in `slack_bolt/version.py` prefixed with "v" (e.g., if version is `1.2.3`, enter `v1.2.3`)
+   6. Click the "Create a new tag" button. This won't create your tag immediately.
+   7. Click the "Generate release notes" button.
+   8. The release name should match the tag name!
+   9. Edit the resulting notes to ensure they have decent messaging that is understandable by non-contributors, but each commit should still have its own line.
+   10. Include a link to the current GitHub Milestone.
+   11. Ensure the "latest release" checkbox is checked to mark this as the latest stable release.
+   12. Publish the release by clicking the "Publish release" button!
+3. Navigate to the [release workflow run](https://github.com/slackapi/bolt-python/actions/workflows/pypi-release.yml). You will need to approve the deployment!
+4. After a few minutes, the corresponding version will be available on <https://pypi.org/project/slack-bolt/>.
+5. Close the current GitHub Milestone and create one for the next patch version.
+6. (Slack Internal) Communicate the release internally
+    - Include a link to the GitHub release
+7. (Slack Internal) Tweet by @SlackAPI
+    - Not necessary for patch updates, might be needed for minor updates,
+      definitely needed for major updates. Include a link to the GitHub release
 
 ## Workflow
 
 ### Versioning and Tags
 
-This project uses semantic versioning, expressed through the numbering scheme of
+This project uses [Semantic Versioning](http://semver.org/), expressed through the numbering scheme of
 [PEP-0440](https://www.python.org/dev/peps/pep-0440/).
 
 ### Branches

.github/release.yml

@@ -0,0 +1,24 @@
+# https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes#configuring-automatically-generated-release-notes
+changelog:
+  categories:
+    - title: 🚀 Enhancements
+      labels:
+        - enhancement
+    - title: 🐛 Bug Fixes
+      labels:
+        - bug
+    - title: 📚 Documentation
+      labels:
+        - docs
+    - title: 🤖 Build
+      labels:
+        - build
+    - title: 🧪 Testing/Code Health
+      labels:
+        - code health
+    - title: 🔒 Security
+      labels:
+        - security
+    - title: 📦 Other changes
+      labels:
+        - "*"

.github/workflows/pypi-release.yml

@@ -0,0 +1,87 @@
+name: Upload A Release to pypi.org or test.pypi.org
+
+on:
+  release:
+    types:
+      - published
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: "Dry run (build only, do not publish)"
+        required: false
+        type: boolean
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        with:
+          ref: ${{ github.event.release.tag_name || github.ref }}
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
+        with:
+          python-version: "3.x"
+
+      - name: Build release distributions
+        run: |
+          scripts/build_pypi_package.sh
+
+      - name: Persist dist folder
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        with:
+          name: release-dist
+          path: dist/
+
+  test-pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    # Run this job for workflow_dispatch events when dry_run input is not 'true'
+    # Note: The comparison is against a string value 'true' since GitHub Actions inputs are strings
+    if: github.event_name == 'workflow_dispatch' && github.event.inputs.dry_run != 'true'
+    environment:
+      name: testpypi
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Retrieve dist folder
+        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
+        with:
+          name: release-dist
+          path: dist/
+
+      - name: Publish release distributions to test.pypi.org
+        # Using OIDC for PyPI publishing (no API tokens needed)
+        # See: https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-pypi
+        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    if: github.event_name == 'release'
+    environment:
+      name: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Retrieve dist folder
+        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
+        with:
+          name: release-dist
+          path: dist/
+
+      - name: Publish release distributions to pypi.org
+        # Using OIDC for PyPI publishing (no API tokens needed)
+        # See: https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-pypi
+        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0