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
$ pyenv install 3.9.6 # select the latest patch version
@@ -40,9 +40,9 @@ $ pyenv rehash
40
40
41
41
Then, you can create a new [Virtual Environment](https://docs.python.org/3/tutorial/venv.html) specific to the Python version you just installed by running:
42
42
43
-
```bash
44
-
$ python -m venv env_3.9.6
45
-
$ source env_3.9.6/bin/activate
43
+
```sh
44
+
python -m venv env_3.9.6
45
+
source env_3.9.6/bin/activate
46
46
```
47
47
48
48
At this point you have a clean, Python-version-specific environment "activated" for
@@ -55,8 +55,8 @@ run `source env_3.9.6/bin/activate` again.
55
55
56
56
The last step is to install this project's dependencies and run all unit tests; to do so, you can run
This project uses code formatting tools to maintain consistent style. You can format the codebase by running:
71
+
72
+
```sh
73
+
./scripts/format.sh
74
+
```
75
+
68
76
### Testing
69
77
70
78
#### Unit Tests
71
79
72
80
When you make changes to this SDK, please write unit tests verifying if the changes work as you expected. You can easily run all the tests and formatting/linter with the below scripts.
73
81
74
-
Run all the unit tests, code formatter, and code analyzer:
82
+
Run all the unit tests, code linter, and code analyzer:
75
83
76
-
```bash
77
-
$ ./scripts/run_validation.sh
84
+
```sh
85
+
./scripts/run_validation.sh
78
86
```
79
87
80
-
Run all the unit tests (no formatter nor code analyzer):
88
+
Run all the unit tests (no linter nor code analyzer):
- It is also possible to include `slack_sdk @ file:///<project path>/dist/slack_sdk-1.2.3-py2.py3-none-any.whl`in a [requirements.txt](https://pip.pypa.io/en/stable/user_guide/#requirements-files) file
@@ -131,75 +139,113 @@ See [`/docs/README`](https://github.com/slackapi/python-slack-sdk/blob/main/docs
131
139
132
140
The API reference is generated from a script. You can generate and preview the **API _reference_ documents for`slack_sdk` package modules** by running:
133
141
134
-
```bash
135
-
$ ./scripts/generate_api_docs.sh
142
+
```sh
143
+
./scripts/generate_api_docs.sh
136
144
```
137
145
138
146
### Releasing
139
147
140
-
1. Create the commit for the release:
141
-
142
-
- Bump the version number in adherence to [Semantic Versioning](http://semver.org/) in`slack_sdk/version.py`.
143
-
- Build the reference docs with `./scripts/generate_api_docs.sh`.
144
-
- Create a branch for the release with `git checkout -b v2.5.0`
145
-
- Make a commit that includes the new version number: `git commit -a -m 'version 2.5.0'`.
146
-
- Open a PR and merge after receiving at least one approval from other maintainers.
147
-
148
-
2. Distribute the release
149
-
150
-
- Use the latest stable Python runtime
151
-
- `python -m venv env`
152
-
- `./scripts/deploy_to_prod_pypi_org.sh`
153
-
- Create a new GitHub Release from the [Releases page](https://github.com/slackapi/python-slack-sdk/releases) by clicking the "Draft a new release" button.
154
-
- Enter the new version number updated from the commit (e.g. `v2.5.0`) into the "Choose a tag" input.
155
-
- Ensure the tag `Target` branch is `main` (e.g `Target:main`).
156
-
- Click the "Create a new tag: x.x.x on publish" button. This won't create your tag immediately.
157
-
- Name the release after the version number updated from the commit (e.g. `version 2.5.0`)
158
-
- Auto-generate the release notes by clicking the "Auto-generate release
159
-
notes" button. This will pull in changes that will be included in your
160
-
release.
161
-
- Edit the resulting notes to ensure they have decent messaging that are
162
-
understandable by non-contributors, but each commit should still have it's
163
-
own line.
164
-
- Ensure that this version adheres to [semantic versioning][semver]. See
165
-
[Versioning](#versioning-and-tags) for correct version format. Version tags
166
-
should match the following pattern: `v2.5.0`.
148
+
#### test.pypi.org deployment
167
149
168
-
```markdown
169
-
Refer to [v{version} milestone](https://github.com/slackapi/python-slack-sdk/milestone/{TODO}?closed=1) to know the complete list of the issues resolved by this release.
150
+
[TestPyPI](https://test.pypi.org/) is a separate instance of the Python Package
151
+
Index that allows you to try distribution tools and processes without affecting
152
+
the real index. This is particularly useful when making changes related to the
153
+
package configuration itself, for example, modifications to the `pyproject.toml` file.
170
154
171
-
**Updates**
155
+
You can deploy this project to TestPyPI using GitHub Actions.
172
156
173
-
1. [WebClient] #111 Make an awesome change - Thanks @SlackHQ
174
-
2. [RTMClient] #222 Make an awesome change - Thanks @SlackAPI
157
+
To deploy using GitHub Actions:
175
158
176
-
**All Changes**
159
+
1. Push your changes to a branch or tag
160
+
2. Navigate to <https://github.com/slackapi/python-slack-sdk/actions/workflows/pypi-release.yml>
161
+
3. Click on "Run workflow"
162
+
4. Select your branch or tag from the dropdown
163
+
5. Click "Run workflow" to build and deploy your branch to TestPyPI
177
164
178
-
* All issues/pull requests: https://github.com/slackapi/python-slack-sdk/milestone/{milestone for the release}
179
-
* All changes: https://github.com/slackapi/python-slack-sdk/compare/{the previous release version tag}...{the release version tag}
180
-
```
165
+
Alternatively, you can deploy from your local machine with:
181
166
182
-
- Close the milestone relating to the Release
183
-
- Create the next patch version Milestone. To be used by the following release.
184
-
185
-
3. (Slack Internal) Communicate the release internally
186
-
187
-
- Include a link to the GitHub release
188
-
189
-
4. Make announcements
190
-
191
-
- #slack-api in dev4slack.slack.com
192
-
- #lang-python in community.slack.com
193
-
194
-
5. (Slack Internal) Tweet by @SlackAPI
167
+
```sh
168
+
./scripts/deploy_to_test_pypi.sh
169
+
```
195
170
196
-
- Not necessary for patch updates, might be needed for minor updates, definitely needed for major updates. Include a link to the GitHub release
171
+
#### Development Deployment
172
+
173
+
Deploying a new version of this library to PyPI is triggered by publishing a GitHub Release.
174
+
Before creating a new release, ensure that everything on a stable branch has
175
+
landed, then [run the tests](#unit-tests).
176
+
177
+
1. Create the commit for the release
178
+
1. Use the latest supported Python version. Using a [virtual environment](#python-and-friends) is recommended.
179
+
2. In `slack_sdk/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).
180
+
- Example: if the current version is `1.2.3`, a proper development bump would be `1.2.4.dev0`
181
+
- `.dev` will indicate to pip that this is a [Development Release](https://peps.python.org/pep-0440/#developmental-releases)
182
+
- Note that the `dev` version can be bumped in development releases: `1.2.4.dev0` ->`1.2.4.dev1`
183
+
3. Build the docs with `./scripts/generate_api_docs.sh`.
184
+
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)
185
+
1. `git checkout -b future-release`
186
+
2. `git add --all` (review files with `git status` before committing)
187
+
3. `git commit -m 'chore(release): version 1.2.4.dev0'`
188
+
4. `git push -u origin future-release`
189
+
2. Create a new GitHub Release
190
+
1. Navigate to the [Releases page](https://github.com/slackapi/python-slack-sdk/releases).
191
+
2. Click the "Draft a new release" button.
192
+
3. Set the "Target" to the feature branch with the development changes.
193
+
4. Click "Tag: Select tag"
194
+
5. Input a new tag name manually. The tag name must match the version in`slack_sdk/version.py` prefixed with "v" (e.g., if version is `1.2.4.dev0`, enter `v1.2.4.dev0`)
195
+
6. Click the "Create a new tag" button. This won't create your tag immediately.
196
+
7. Click the "Generate release notes" button.
197
+
8. The release name should match the tag name!
198
+
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.
199
+
10. Set this release as a pre-release.
200
+
11. Publish the release by clicking the "Publish release" button!
201
+
3. Navigate to the [release workflow run](https://github.com/slackapi/python-slack-sdk/actions/workflows/pypi-release.yml). You will need to approve the deployment!
202
+
4. After a few minutes, the corresponding version will be available on <https://pypi.org/project/slack-sdk>.
203
+
5. (Slack Internal) Communicate the release internally
204
+
205
+
#### Production Deployment
206
+
207
+
Deploying a new version of this library to PyPI is triggered by publishing a GitHub Release.
208
+
Before creating a new release, ensure that everything on the `main` branch since
209
+
the last tag is in a releasable state! At a minimum, [run the tests](#unit-tests).
210
+
211
+
1. Create the commit for the release
212
+
1. Use the latest supported Python version. Using a [virtual environment](#python-and-friends) is recommended.
213
+
2. In `slack_sdk/version.py` bump the version number in adherence to [Semantic Versioning](http://semver.org/) and the [Versioning](#versioning-and-tags) section.
214
+
3. Build the docs with `./scripts/generate_api_docs.sh`.
215
+
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.
216
+
1. `git checkout -b 1.2.3-release`
217
+
2. `git add --all` (review files with `git status` before committing)
218
+
3. `git commit -m 'chore(release): version 1.2.3'`
219
+
4. `git push -u origin 1.2.3-release`
220
+
5. Add relevant labels to the PR and add the PR to a GitHub Milestone.
221
+
6. Merge in release PR after getting an approval from at least one maintainer.
222
+
2. Create a new GitHub Release
223
+
1. Navigate to the [Releases page](https://github.com/slackapi/python-slack-sdk/releases).
224
+
2. Click the "Draft a new release" button.
225
+
3. Set the "Target" to the `main` branch.
226
+
4. Click "Tag: Select tag"
227
+
5. Input a new tag name manually. The tag name must match the version in `slack_sdk/version.py` prefixed with "v" (e.g., if version is `1.2.3`, enter `v1.2.3`)
228
+
6. Click the "Create a new tag" button. This won't create your tag immediately.
229
+
7. Click the "Generate release notes" button.
230
+
8. The release name should match the tag name!
231
+
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.
232
+
10. Include a link to the current GitHub Milestone.
233
+
11. Ensure the "latest release" checkbox is checked to mark this as the latest stable release.
234
+
12. Publish the release by clicking the "Publish release" button!
235
+
3. Navigate to the [release workflow run](https://github.com/slackapi/python-slack-sdk/actions/workflows/pypi-release.yml). You will need to approve the deployment!
236
+
4. After a few minutes, the corresponding version will be available on <https://pypi.org/project/slack-sdk>.
237
+
5. Close the current GitHub Milestone and create one for the next patch version.
238
+
6. (Slack Internal) Communicate the release internally
239
+
- Include a link to the GitHub release
240
+
7. (Slack Internal) Tweet by @SlackAPI
241
+
- Not necessary for patch updates, might be needed for minor updates,
242
+
definitely needed for major updates. Include a link to the GitHub release
197
243
198
244
## Workflow
199
245
200
246
### Versioning and Tags
201
247
202
-
This project uses semantic versioning, expressed through the numbering scheme of
248
+
This project uses [Semantic Versioning](http://semver.org/), expressed through the numbering scheme of
0 commit comments