Skip to content

chore: improve the release instructions #76

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 1 commit into from
Nov 5, 2025
Merged

chore: improve the release instructions #76

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
143 changes: 53 additions & 90 deletions .github/maintainers_guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -134,113 +134,76 @@ 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_cli_hooks/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`
- 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/python-slack-hooks/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_cli_hooks/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_cli_hooks/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
<https://pypi.org/project/slack-cli-hooks/>.
10. (Slack Internal) Communicate the release internally
1. Create the commit for the release
1. In `slack_cli_hooks/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`
Comment on lines +143 to +145
Copy link
Member

@zimeg zimeg Nov 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👾 question: Would we still want this to be development releases for the next minor version?

1.3.0.dev0

🗣️ ramble: Some confusion exists for projects IMHO where we've tagged patch release RCs that end up released under the next minor version - I understand these RCs most common for major or minor versions!

Copy link
Contributor Author

@WilliamBergamin WilliamBergamin Nov 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it depends on the changes included in the development version, if the changes are scoped to a minor then we should bump the minor version rather then the patch, example 1.2.3 would become 1.3.0.dev0

what is found in the maintainers guide is an example, but the maintainer performing the release should use their judgment to determine the correct semver version 🧠

2. 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/python-slack-hooks/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_cli_hooks/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/python-slack-hooks/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-cli-hooks>.
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_cli_hooks/version.py`
- 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/python-slack-hooks/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_cli_hooks/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_cli_hooks/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
<https://pypi.org/project/slack-cli-hooks/>.
9. Close the current GitHub Milestone and create one for the next minor version.
10. (Slack Internal) Communicate the release internally
1. In `slack_cli_hooks/version.py` bump the version number in adherence to [Semantic Versioning](http://semver.org/) and the [Versioning](#versioning-and-tags) section.
2. 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`
3. Add relevant labels to the PR and add the PR to a GitHub Milestone.
4. 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/python-slack-hooks/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_cli_hooks/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/python-slack-hooks/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-cli-hooks>.
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

## 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
2 changes: 1 addition & 1 deletion .github/workflows/pypi-release.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ jobs:
name: release-dist
path: dist/

- name: Publish release distributions to test.pypi.org
- 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