chore: automate release process

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
+```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,7 +34,7 @@ $ pyenv rehash
 
 Then, you can create a new Virtual Environment this way:
 
-```bash
+```sh
 $ python -m venv env_3.8.5
 $ source env_3.8.5/bin/activate
 ```
@@ -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
+```sh
 $ ./scripts/install_all_and_run_tests.sh
 ```
 
 Once you installed all the required dependencies, you can use the following one.
 
-```bash
+```sh
 $ ./scripts/run_tests.sh
 ```
 
 Also, you can run a single test this way.
 
-```bash
+```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,115 +97,154 @@ 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.
+
+To deploy using GitHub Actions:
 
-```toml
-[testpypi]
-username: {your username}
-password: {your password}
+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
 
+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 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`
-      - `.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
+   - 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.2.3.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.2.3.dev0` -> `1.2.3.dev1`
+   - Build the docs with `./scripts/generate_api_docs.sh`.
+   - Commit with a message including the new version number. For example
+     `1.2.3.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.2.3.dev0'`
+     - `git push -u origin future-release`
+2. Create a new GitHub Release from the
+   [Releases page](https://github.com/slackapi/bolt-python/releases) by
+   clicking the "Draft a new release" button.
+3. Input the version manually into the "Choose a tag" input. You must use the
+   same version found in `slack_bolt/version.py`
+
+   - After you input the new version, click the "Create a new tag: x.x.x on
+     publish" button. This won't create your tag immediately.
+   - 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/) and
+     [Developmental Release](https://peps.python.org/pep-0440/#developmental-releases).
+     See [Versioning](#versioning-and-tags) for correct version format.
+
+4. Set the "Target" input to the feature branch with the development changes.
+5. Name the release title after the version tag. It should match the updated
+   value from `slack_bolt/version.py`!
+6. Make any adjustments to generated release notes to make sure they are
+   accessible and approachable and that an end-user with little context about
+   this project could still understand.
+7. Select "Set as a pre-release"
+8. Publish the release by clicking the "Publish release" button!
+9. After a few minutes, the corresponding version will be available on
+   <https://github.com/slackapi/bolt-python/>.
+10. (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`
+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
+   - 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
+   - 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 1.2.3-release`
+     - `git commit -m 'chore(release): tag version 1.2.3'`
+     - `git push {your-fork} 1.2.3-release`
+   - Add relevant labels to the PR and add the PR to a GitHub Milestone.
+   - Merge in release PR after getting an approval from at least one maintainer.
+2. Create a new GitHub Release from the
+   [Releases page](https://github.com/slackapi/bolt-python/releases) by
+   clicking the "Draft a new release" button.
+3. Input the version manually into the "Choose a tag" input. You must use the
+   same version found in `slack_bolt/version.py`
+
+   - After you input the version, click the "Create a new tag: x.x.x on publish"
+     button. This won't create your tag immediately.
+   - Click 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.
+
+4. Set the "Target" input to the "main" branch.
+5. Name the release title after the version tag. It should match the updated
+   value from `slack_bolt/version.py`!
+6. Make any adjustments to generated release notes to make sure they are
+   accessible and approachable and that an end-user with little context about
+   this project could still understand.
+7. Publish the release by clicking the "Publish release" button!
+8. After a few minutes, the corresponding version will be available on
+   <https://pypi.org/project/slack-bolt/>.
+9. Close the current GitHub Milestone and create one for the next minor version.
+10. (Slack Internal) Communicate the release internally
+    - Include a link to the GitHub release
+11. (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
 

.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:
+        - "*"