Skip to content

chore: automate release process #1394

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
WilliamBergamin merged 4 commits into from
Nov 5, 2025
Merged

chore: automate release process #1394

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
55dd604
chore: automate release process
WilliamBergamin Nov 4, 2025
cf54914
Update maintainers_guide.md
WilliamBergamin Nov 4, 2025
043f1af
Improve the release instruction based on feedback
WilliamBergamin Nov 5, 2025
a6a6a85
Update maintainers_guide.md
WilliamBergamin Nov 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
200 changes: 101 additions & 99 deletions .github/maintainers_guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down
24 changes: 24 additions & 0 deletions .github/release.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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:
- "*"
87 changes: 87 additions & 0 deletions .github/workflows/pypi-release.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Loading
Loading