Skip to content

Commit d9e93af

Browse files
WilliamBergaminWilliamBergamin
authored
feat: automate releases (#36)
* Automate release * Update maintainers_guide.md * Improve wording
1 parent a050a47 commit d9e93af

4 files changed

Lines changed: 128 additions & 61 deletions

File tree

‎.github/maintainers_guide.md‎

Lines changed: 93 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -108,66 +108,109 @@ If you want to test the package locally you can.
108108

109109
#### test.pypi.org deployment
110110

111-
It is possible to deploy this project on <https://test.pypi.org/> in order to try out packaging and deploy related changes
111+
[TestPyPI](https://test.pypi.org/) is a separate instance of the
112+
Python Package Index that allows you to try distribution tools and
113+
processes without affecting the real index. This is useful with changes that
114+
relate to the package itself, example the contents of the `pyproject.toml`
115+
116+
The following can be used to deploy this project on <https://test.pypi.org/>.
112117

113118
```zsh
114-
./scripts/deploy_to_test_pypi.sh
119+
# Set the new version with SLACK_CLI_HOOKS_VERSION
120+
SLACK_CLI_HOOKS_VERSION="1.2.3" ./scripts/deploy_to_test_pypi.sh
115121
```
116122

117123
#### Development Deployment
118124

119-
1. Create a branch in which the development release will live:
120-
- 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_cli_hooks/version.py`
121-
- Example the current version is `1.2.3` a proper development bump would be `1.3.0.dev0`
122-
- `.dev` will indicate to pip that this is a [Development Release](https://peps.python.org/pep-0440/#developmental-releases)
123-
- Note that the `dev` version can be bumped in development releases: `1.3.0.dev0` -> `1.3.0.dev1`
124-
- 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)
125-
- `git checkout -b future-release`
126-
- `git add slack_cli_hooks/version.py`
127-
- `git commit -m 'version 1.3.0.dev0'`
128-
- `git push future-release`
129-
- Create a git tag for the release. For example `git tag 1.3.0.dev0`.
130-
- Push the tag up to github with `git push origin --tags`
131-
132-
2. Distribute the release
133-
- Use the latest stable Python runtime
134-
- `python -m venv .venv`
135-
- `scripts/deploy_to_prod_pypi.sh`
136-
- You do not need to create a GitHub release
137-
138-
3. (Slack Internal) Communicate the release internally
125+
Releases for this library are automatically generated off of git releases. Before
126+
creating a new release, ensure that everything on a stable branch has landed, then
127+
[run the tests](#run-all-the-unit-tests).
128+
129+
1. Create a new GitHub Release from the
130+
[Releases page](https://github.com/slackapi/python-slack-hooks/releases) by
131+
clicking the "Draft a new release" button.
132+
2. Input a new version manually into the "Choose a tag" input. You can start off
133+
by incrementing the version to reflect a patch. (i.e. 1.16.0 -> 1.16.1.dev0)
134+
135+
- Example the current version is `1.2.3` a proper development bump would be `1.3.0.dev0`
136+
- `.dev` will indicate to pip that this is a [Development Release](https://peps.python.org/pep-0440/#developmental-releases)
137+
- Note that the `dev` version can be bumped in development releases: `1.3.0.dev0` -> `1.3.0.dev1`
138+
- After you input the new version, click the "Create a new tag: x.x.x on
139+
publish" button. This won't create your tag immediately.
140+
- Auto-generate the release notes by clicking the "Auto-generate release
141+
notes" button. This will pull in changes that will be included in your
142+
release.
143+
- Edit the resulting notes to ensure they have decent messaging that are
144+
understandable by non-contributors, but each commit should still have it's
145+
own line.
146+
- Flip to the preview mode and review the pull request labels of the changes
147+
included in this release (i.e. `semver:minor` `semver:patch`,
148+
`semver:major`). Tip: Your release version should be based on the tag of
149+
the largest change, so if this release includes a `semver:minor`, the
150+
release version in your tag should be upgraded to reflect a minor.
151+
- Ensure that this version adheres to [semantic versioning](http://semver.org/) and
152+
[Developmental Release](https://peps.python.org/pep-0440/#developmental-releases).
153+
See [Versioning](#versioning-and-tags) for correct version format. Version tags
154+
should match the following pattern: `1.0.1` (no `v` preceding the number).
155+
156+
3. Set the "Target" input to the feature branch with the development changes.
157+
4. Name the release title after the version tag. The release title is what will
158+
be used by the pipeline to populate the value in `slack_cli_hooks/version.py`
159+
and the Pypi package version!
160+
5. Make any adjustments to generated release notes to make sure they are
161+
accessible and approachable and that an end-user with little context about
162+
this project could still understand.
163+
6. Select "Set as a pre-release"
164+
7. Publish the release by clicking the "Publish release" button!
165+
8. After a few minutes, the corresponding version will be available on
166+
<https://pypi.org/project/slack-cli-hooks/>.
167+
9. (Slack Internal) Communicate the release internally
139168

140169
#### Production Deployment
141170

142-
1. Create the commit for the release:
143-
- Bump the version number in adherence to [Semantic Versioning](http://semver.org/) in `slack_cli_hooks/version.py`
144-
- 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.
145-
- `git checkout -b 1.2.3-release`
146-
- `git add slack_cli_hooks/version.py`
147-
- `git commit -m 'version 1.2.3'`
148-
- `git push {your-fork} 1.2.3-release`
149-
- Create a release PR and get an approval from at least one maintainer.
150-
- Merge in your release PR.
151-
152-
2. Distribute the release
153-
- Use the latest stable Python runtime
154-
- `python -m venv .venv`
155-
- `/scripts/deploy_to_prod_pypi.sh`
156-
- Create a GitHub release - <https://github.com/slackapi/python-slack-hooks/releases>
157-
- Click `Draft a new release`
158-
- Input the new version you set in [version.py](../slack_cli_hooks/version.py) manually as the `choose a tag` input (example `1.2.3`)
159-
- After you input the new version, click the "Create a new tag: x.x.x on publish" button.
160-
- Set the "Target" input to the "main" branch.
161-
- Name the release title after the version tag.
162-
- Auto-generate the release notes by clicking the "Auto-generate release notes" button.
163-
- 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.
164-
- Publish the release by clicking the "Publish release" button!
165-
166-
3. (Slack Internal) Communicate the release internally
171+
Releases for this library are automatically generated off of git releases. Before
172+
creating a new release, ensure that everything on the `main` branch since the
173+
last tag is in a releasable state! At a minimum,
174+
[run the tests](#run-all-the-unit-tests).
175+
176+
1. Create a new GitHub Release from the
177+
[Releases page](https://github.com/slackapi/python-slack-hooks/releases) by
178+
clicking the "Draft a new release" button.
179+
2. Input a new version manually into the "Choose a tag" input. You can start off
180+
by incrementing the version to reflect a patch. (i.e. 1.16.0 -> 1.16.1)
181+
182+
- After you input the new version, click the "Create a new tag: x.x.x on
183+
publish" button. This won't create your tag immediately.
184+
- Auto-generate the release notes by clicking the "Auto-generate release
185+
notes" button. This will pull in changes that will be included in your
186+
release.
187+
- Edit the resulting notes to ensure they have decent messaging that are
188+
understandable by non-contributors, but each commit should still have it's
189+
own line.
190+
- Flip to the preview mode and review the pull request labels of the changes
191+
included in this release (i.e. `semver:minor` `semver:patch`,
192+
`semver:major`). Tip: Your release version should be based on the tag of
193+
the largest change, so if this release includes a `semver:minor`, the
194+
release version in your tag should be upgraded to reflect a minor.
195+
- Ensure that this version adheres to [semantic versioning](http://semver.org/). See
196+
[Versioning](#versioning-and-tags) for correct version format. Version tags
197+
should match the following pattern: `1.0.1` (no `v` preceding the number).
198+
199+
3. Set the "Target" input to the "main" branch.
200+
4. Name the release title after the version tag. The release title is what will
201+
be used by the pipeline to populate the value in `slack_cli_hooks/version.py`
202+
and the Pypi package version!
203+
5. Make any adjustments to generated release notes to make sure they are
204+
accessible and approachable and that an end-user with little context about
205+
this project could still understand.
206+
6. Publish the release by clicking the "Publish release" button!
207+
7. After a few minutes, the corresponding version will be available on
208+
<https://pypi.org/project/slack-cli-hooks/>.
209+
8. (Slack Internal) Communicate the release internally
167210
- Include a link to the GitHub release
168-
169-
4. (Slack Internal) Tweet by @SlackAPI
170-
- Not necessary for patch updates, might be needed for minor updates, definitely needed for major updates. Include a link to the GitHub release
211+
9. (Slack Internal) Tweet by @SlackAPI
212+
- Not necessary for patch updates, might be needed for minor updates,
213+
definitely needed for major updates. Include a link to the GitHub release
171214

172215
## Workflow
173216

‎.github/workflows/release.yml‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
name: Upload A Release To Pypi
2+
3+
on:
4+
release:
5+
types: [published]
6+
7+
jobs:
8+
deploy:
9+
runs-on: ubuntu-latest
10+
steps:
11+
- uses: actions/checkout@v4
12+
- name: Set up Python
13+
uses: actions/setup-python@v4
14+
with:
15+
python-version: "3.x"
16+
- name: Install dependencies
17+
run: |
18+
python -m pip install --upgrade pip
19+
pip install build
20+
pip install twine
21+
- name: Build package
22+
run: |
23+
python -m build
24+
twine check dist/*
25+
env:
26+
SLACK_CLI_HOOKS_VERSION: ${{ github.event.release.name }}
27+
- name: Publish package
28+
run: twine upload dist/*
29+
env:
30+
TWINE_USERNAME: ${{ secrets.PYPI_USER }}
31+
TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }}

‎scripts/deploy_to_prod_pypi.sh‎

Lines changed: 0 additions & 10 deletions
This file was deleted.

‎slack_cli_hooks/version.py‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,5 @@
11
"""Check the latest version at https://pypi.org/project/slack-cli-hooks/"""
2-
__version__ = "0.0.0.dev2"
2+
3+
import os
4+
5+
__version__ = os.environ.get("SLACK_CLI_HOOKS_VERSION", "0.0.0.dev0")

0 commit comments

Comments
 (0)