From 55dd6041f2bd5a665629297d936604544be413d5 Mon Sep 17 00:00:00 2001 From: William Bergamin Date: Tue, 4 Nov 2025 17:44:35 -0500 Subject: [PATCH 1/4] chore: automate release process --- .github/maintainers_guide.md | 219 +++++++++++------- .github/release.yml | 24 ++ .github/workflows/pypi-release.yml | 87 +++++++ scripts/deploy_to_pypi_org.sh | 12 - ...est_pypi_org.sh => deploy_to_test_pypi.sh} | 0 5 files changed, 240 insertions(+), 102 deletions(-) create mode 100644 .github/release.yml create mode 100644 .github/workflows/pypi-release.yml delete mode 100755 scripts/deploy_to_pypi_org.sh rename scripts/{deploy_to_test_pypi_org.sh => deploy_to_test_pypi.sh} (100%) diff --git a/.github/maintainers_guide.md b/.github/maintainers_guide.md index 352398072..d5fce942e 100644 --- a/.github/maintainers_guide.md +++ b/.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. -```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,19 +49,19 @@ 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 ``` @@ -69,7 +69,7 @@ $ ./scripts/run_tests.sh tests/scenario_tests/test_app.py 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 /dist/slack_bolt-1.2.3-py2.py3-none-any.whl ``` - It is also possible to include `slack_bolt @ file:////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 +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 + . +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 + . +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 diff --git a/.github/release.yml b/.github/release.yml new file mode 100644 index 000000000..b2574b7cc --- /dev/null +++ b/.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: + - "*" diff --git a/.github/workflows/pypi-release.yml b/.github/workflows/pypi-release.yml new file mode 100644 index 000000000..21b472247 --- /dev/null +++ b/.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 diff --git a/scripts/deploy_to_pypi_org.sh b/scripts/deploy_to_pypi_org.sh deleted file mode 100755 index 8c5234902..000000000 --- a/scripts/deploy_to_pypi_org.sh +++ /dev/null @@ -1,12 +0,0 @@ -#!/bin/bash - -script_dir=`dirname $0` -cd ${script_dir}/.. -rm -rf ./slack_bolt.egg-info - -pip install -U pip && \ - pip install -U twine build && \ - rm -rf dist/ build/ slack_bolt.egg-info/ && \ - python -m build --sdist --wheel && \ - twine check dist/* && \ - twine upload dist/* diff --git a/scripts/deploy_to_test_pypi_org.sh b/scripts/deploy_to_test_pypi.sh similarity index 100% rename from scripts/deploy_to_test_pypi_org.sh rename to scripts/deploy_to_test_pypi.sh From cf54914d0cae947d2113f851da60952630480c65 Mon Sep 17 00:00:00 2001 From: William Bergamin Date: Tue, 4 Nov 2025 17:58:08 -0500 Subject: [PATCH 2/4] Update maintainers_guide.md --- .github/maintainers_guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/maintainers_guide.md b/.github/maintainers_guide.md index d5fce942e..0f52538a2 100644 --- a/.github/maintainers_guide.md +++ b/.github/maintainers_guide.md @@ -192,7 +192,7 @@ landed, then [run the tests](#run-all-the-unit-tests). 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 - . + . 10. (Slack Internal) Communicate the release internally #### Production Deployment From 043f1af4830ac621d6051fa9c2bb346890e6226d Mon Sep 17 00:00:00 2001 From: William Bergamin Date: Wed, 5 Nov 2025 11:21:02 -0500 Subject: [PATCH 3/4] Improve the release instruction based on feedback --- .github/maintainers_guide.md | 161 ++++++++++++++--------------------- 1 file changed, 62 insertions(+), 99 deletions(-) diff --git a/.github/maintainers_guide.md b/.github/maintainers_guide.md index 0f52538a2..31319720c 100644 --- a/.github/maintainers_guide.md +++ b/.github/maintainers_guide.md @@ -11,8 +11,8 @@ 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: ```sh -$ brew update -$ brew install pyenv +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. @@ -35,8 +35,8 @@ $ pyenv rehash Then, you can create a new Virtual Environment this way: ```sh -$ python -m venv env_3.8.5 -$ source env_3.8.5/bin/activate +python -m venv env_3.8.5 +source env_3.8.5/bin/activate ``` ## Tasks @@ -50,19 +50,19 @@ 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. ```sh -$ ./scripts/install_all_and_run_tests.sh +./scripts/install_all_and_run_tests.sh ``` Once you installed all the required dependencies, you can use the following one. ```sh -$ ./scripts/run_tests.sh +./scripts/run_tests.sh ``` Also, you can run a single test this way. ```sh -$ ./scripts/run_tests.sh tests/scenario_tests/test_app.py +./scripts/run_tests.sh tests/scenario_tests/test_app.py ``` #### Run the Samples @@ -142,107 +142,70 @@ Alternatively, you can deploy from your local machine with: #### Development Deployment -Deploying a new version of this library to Pypi is triggered by publishing a 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 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.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 - . -10. (Slack Internal) Communicate the release internally +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.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 '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 . +5. (Slack Internal) Communicate the release internally #### Production Deployment -Deploying a new version of this library to Pypi is triggered by publishing a 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). +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 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 - . -9. Close the current GitHub Milestone and create one for the next minor version. -10. (Slack Internal) Communicate the release internally + 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): tag 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 . +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 -11. (Slack Internal) Tweet by @SlackAPI +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 @@ -250,7 +213,7 @@ the last tag is in a releasable state! At a minimum, ### 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 From a6a6a85c0d98703eb65c88ee9d81e5cf7e0e07b0 Mon Sep 17 00:00:00 2001 From: William Bergamin Date: Wed, 5 Nov 2025 11:33:56 -0500 Subject: [PATCH 4/4] Update maintainers_guide.md --- .github/maintainers_guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/maintainers_guide.md b/.github/maintainers_guide.md index 31319720c..8cd600271 100644 --- a/.github/maintainers_guide.md +++ b/.github/maintainers_guide.md @@ -154,7 +154,7 @@ landed, then [run the tests](#run-all-the-unit-tests). 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 'version 1.2.4.dev0'` + 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). @@ -183,7 +183,7 @@ the last tag is in a releasable state! At a minimum, [run the tests](#run-all-th 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): tag version 1.2.3'` + 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.