You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -10,14 +10,14 @@ this project. If you use this package within your own software as is but don't p
10
10
11
11
We recommend using [pyenv](https://github.com/pyenv/pyenv) for Python runtime management. If you use macOS, follow the following steps:
12
12
13
-
```bash
14
-
$ brew update
15
-
$ brew install pyenv
13
+
```sh
14
+
brew update
15
+
brew install pyenv
16
16
```
17
17
18
18
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>
- 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
111
111
112
-
### Releasing
113
-
114
-
#### Generate API reference documents
112
+
### Generate API reference documents
115
113
116
-
```bash
114
+
```sh
117
115
./scripts/generate_api_docs.sh
118
116
```
119
117
118
+
### Releasing
119
+
120
120
#### test.pypi.org deployment
121
121
122
-
##### $HOME/.pypirc
122
+
[TestPyPI](https://test.pypi.org/) is a separate instance of the Python Package
123
+
Index that allows you to try distribution tools and processes without affecting
124
+
the real index. This is particularly useful when making changes related to the
125
+
package configuration itself, for example, modifications to the `pyproject.toml` file.
126
+
127
+
You can deploy this project to TestPyPI using GitHub Actions.
123
128
124
-
```toml
125
-
[testpypi]
126
-
username: {your username}
127
-
password: {your password}
129
+
To deploy using GitHub Actions:
130
+
131
+
1. Push your changes to a branch or tag
132
+
2. Navigate to <https://github.com/slackapi/bolt-python/actions/workflows/pypi-release.yml>
133
+
3. Click on "Run workflow"
134
+
4. Select your branch or tag from the dropdown
135
+
5. Click "Run workflow" to build and deploy your branch to TestPyPI
136
+
137
+
Alternatively, you can deploy from your local machine with:
138
+
139
+
```sh
140
+
./scripts/deploy_to_test_pypi.sh
128
141
```
129
142
130
143
#### Development Deployment
131
144
132
-
1. Create a branch in which the development release will live:
133
-
- 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`
134
-
- Example the current version is `1.2.3` a proper development bump would be `1.3.0.dev0`
145
+
Deploying a new version of this library to PyPI is triggered by publishing a GitHub Release.
146
+
Before creating a new release, ensure that everything on a stable branch has
147
+
landed, then [run the tests](#run-all-the-unit-tests).
148
+
149
+
1. Create the commit for the release
150
+
1. Use the latest supported Python version. Using a [virtual environment](#python-and-friends) is recommended.
151
+
2. 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).
152
+
- Example: if the current version is `1.2.3`, a proper development bump would be `1.2.4.dev0`
135
153
- `.dev` will indicate to pip that this is a [Development Release](https://peps.python.org/pep-0440/#developmental-releases)
136
-
- Note that the `dev` version can be bumped in development releases: `1.3.0.dev0` ->`1.3.0.dev1`
137
-
- 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)
138
-
- `git checkout -b future-release`
139
-
- `git commit -m 'version 1.3.0.dev0'`
140
-
- `git push future-release`
141
-
- Create a git tag for the release. For example `git tag v1.3.0.dev0`.
142
-
- Push the tag up to github with `git push origin --tags`
143
-
144
-
2. Distribute the release
145
-
- Use the latest stable Python runtime
146
-
- `python -m venv .venv`
147
-
- `./scripts/deploy_to_pypi_org.sh`
148
-
- You do not need to create a GitHub release
149
-
150
-
3. (Slack Internal) Communicate the release internally
154
+
- Note that the `dev` version can be bumped in development releases: `1.2.4.dev0` ->`1.2.4.dev1`
155
+
3. Build the docs with `./scripts/generate_api_docs.sh`.
156
+
4. 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)
157
+
1. `git checkout -b future-release`
158
+
2. `git add --all` (review files with `git status` before committing)
159
+
3. `git commit -m 'chore(release): version 1.2.4.dev0'`
160
+
4. `git push -u origin future-release`
161
+
2. Create a new GitHub Release
162
+
1. Navigate to the [Releases page](https://github.com/slackapi/bolt-python/releases).
163
+
2. Click the "Draft a new release" button.
164
+
3. Set the "Target" to the feature branch with the development changes.
165
+
4. Click "Tag: Select tag"
166
+
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`)
167
+
6. Click the "Create a new tag" button. This won't create your tag immediately.
168
+
7. Click the "Generate release notes" button.
169
+
8. The release name should match the tag name!
170
+
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.
171
+
10. Set this release as a pre-release.
172
+
11. Publish the release by clicking the "Publish release" button!
173
+
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!
174
+
4. After a few minutes, the corresponding version will be available on <https://pypi.org/project/slack-bolt>.
175
+
5. (Slack Internal) Communicate the release internally
151
176
152
177
#### Production Deployment
153
178
154
-
1. Create the commit for the release:
155
-
- Bump the version number in adherence to [Semantic Versioning](http://semver.org/) in`slack_bolt/version.py`
156
-
- Build the docs with `./scripts/generate_api_docs.sh`.
157
-
- 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.
158
-
- `git checkout -b v1.2.3`
159
-
- `git commit -a -m 'version 1.2.3'`
160
-
- `git push -u origin HEAD`
161
-
- Open a PR and merge after receiving at least one approval from other maintainers.
162
-
163
-
2. Distribute the release
164
-
- Use the latest stable Python runtime
165
-
- `git checkout main && git pull`
166
-
- `python --version`
167
-
- `python -m venv .venv`
168
-
- `./scripts/deploy_to_pypi_org.sh`
169
-
- Create a new GitHub Release from the [Releases page](https://github.com/slackapi/bolt-python/releases) by clicking the "Draft a new release" button.
170
-
- Enter the new version number updated from the commit (e.g. `v1.2.3`) into the "Choose a tag" input.
171
-
- Ensure the tag `Target` branch is `main` (e.g `Target:main`).
172
-
- Click the "Create a new tag: x.x.x on publish" button. This won't create your tag immediately.
173
-
- Name the release after the version number updated from the commit (e.g. `version 1.2.3`)
174
-
- Auto-generate the release notes by clicking the "Auto-generate release
175
-
notes" button. This will pull in changes that will be included in your
176
-
release.
177
-
- Edit the resulting notes to ensure they have decent messaging that are
178
-
understandable by non-contributors, but each commit should still have it's
179
-
own line.
180
-
- Ensure that this version adheres to [semantic versioning](http://semver.org/). See
181
-
[Versioning](#versioning-and-tags) for correct version format. Version tags
182
-
should match the following pattern: `v2.5.0`.
183
-
184
-
```markdown
185
-
## New Features
186
-
187
-
### Awesome Feature 1
188
-
189
-
Description here.
190
-
191
-
### Awesome Feature 2
192
-
193
-
Description here.
194
-
195
-
## Changes
196
-
197
-
*#123 Make it better - thanks @SlackHQ
198
-
* #123 Fix something wrong - thanks @seratch
199
-
```
200
-
201
-
3. (Slack Internal) Communicate the release internally
202
-
- Include a link to the GitHub release
203
-
204
-
4. Make announcements
205
-
- #tools-bolt in community.slack.com
206
-
207
-
5. (Slack Internal) Tweet by @SlackAPI
208
-
- Not necessary for patch updates, might be needed for minor updates, definitely needed for major updates. Include a link to the GitHub release
179
+
Deploying a new version of this library to PyPI is triggered by publishing a GitHub Release.
180
+
Before creating a new release, ensure that everything on the `main` branch since
181
+
the last tag is in a releasable state! At a minimum, [run the tests](#run-all-the-unit-tests).
182
+
183
+
1. Create the commit for the release
184
+
1. Use the latest supported Python version. Using a [virtual environment](#python-and-friends) is recommended.
185
+
2. In `slack_bolt/version.py` bump the version number in adherence to [Semantic Versioning](http://semver.org/) and the [Versioning](#versioning-and-tags) section.
186
+
3. Build the docs with `./scripts/generate_api_docs.sh`.
187
+
4. 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.
188
+
1. `git checkout -b 1.2.3-release`
189
+
2. `git add --all` (review files with `git status` before committing)
190
+
3. `git commit -m 'chore(release): version 1.2.3'`
191
+
4. `git push -u origin 1.2.3-release`
192
+
5. Add relevant labels to the PR and add the PR to a GitHub Milestone.
193
+
6. Merge in release PR after getting an approval from at least one maintainer.
194
+
2. Create a new GitHub Release
195
+
1. Navigate to the [Releases page](https://github.com/slackapi/bolt-python/releases).
196
+
2. Click the "Draft a new release" button.
197
+
3. Set the "Target" to the `main` branch.
198
+
4. Click "Tag: Select tag"
199
+
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`)
200
+
6. Click the "Create a new tag" button. This won't create your tag immediately.
201
+
7. Click the "Generate release notes" button.
202
+
8. The release name should match the tag name!
203
+
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.
204
+
10. Include a link to the current GitHub Milestone.
205
+
11. Ensure the "latest release" checkbox is checked to mark this as the latest stable release.
206
+
12. Publish the release by clicking the "Publish release" button!
207
+
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!
208
+
4. After a few minutes, the corresponding version will be available on <https://pypi.org/project/slack-bolt/>.
209
+
5. Close the current GitHub Milestone and create one for the next patch version.
210
+
6. (Slack Internal) Communicate the release internally
211
+
- Include a link to the GitHub release
212
+
7. (Slack Internal) Tweet by @SlackAPI
213
+
- Not necessary for patch updates, might be needed for minor updates,
214
+
definitely needed for major updates. Include a link to the GitHub release
209
215
210
216
## Workflow
211
217
212
218
### Versioning and Tags
213
219
214
-
This project uses semantic versioning, expressed through the numbering scheme of
220
+
This project uses [Semantic Versioning](http://semver.org/), expressed through the numbering scheme of
0 commit comments