# Releases (Python)
This guide provides Python-specific release commands and workflows.
For language-neutral release principles, see the
[release guide](releases.md).
The project follows [semantic versioning](https://semver.org/) for releases.
## Release Process
### Pre-Release Quality Check
Run local quality assurance before any release process:
git status && git pull origin master
hatch --env develop run make-all
Also, ensure that at least one news fragment exists under `.auxiliary/data/towncrier`.
### Initial Release Candidate
1. **Branch Setup**: Checkout `master` branch and ensure it's up to date:
git checkout master
git pull origin master
2. **Create Release Branch**: Checkout new release branch:
git checkout -b release-.
3. **Version Bump**: Bump alpha to release candidate and commit:
hatch version rc
git commit -am "Version: $(hatch version)"
4. **Tag Release Candidate**:
git tag -m "Release candidate v$(hatch version)." v$(hatch version)
5. **Push Branch and Tag**: Push release branch and tag to upstream:
git push -u origin release-.
git push --tags
6. **Setup Next Development Cycle**: Return to `master` and prepare for next version:
git checkout master
hatch version minor,alpha
next_release="$(hatch version | sed 's/a[0-9]*$//')"
git commit -am "Start of development for release ${next_release}."
git tag -m "Start of development for release ${next_release}." "i${next_release}"
git push origin master --tags
### Final Release
1. **Branch Setup**: Checkout and update the release branch:
git checkout release-.
git pull origin release-.
2. **Version Finalization**: Bump release candidate to final release:
hatch version release
git commit -am "Version: $(hatch version)"
3. **Changelog Generation**: Run Towncrier to build final changelog:
hatch --env develop run towncrier build --keep --version $(hatch version)
git commit -am "Update changelog for v$(hatch version)."
4. **Release Tag**: Create signed release tag:
git tag -m "" v$(hatch version)
5. **Push Release**: Push release branch and tag to upstream:
git push origin release-.
git push --tags
6. **Monitor Release**: Wait for the release workflow to complete successfully. Check the GitHub Actions tab to monitor progress.
7. **Post-Release Cleanup**: Clean up news fragments and push:
git rm .auxiliary/data/towncrier/*.rst
git commit -m "Clean up news fragments."
git push origin release-.
8. **Master Integration**: Cherry-pick release commits back to `master`:
git checkout master
git pull origin master
git cherry-pick
git cherry-pick
git push origin master
Use `git log --oneline` on the release branch to identify commit hashes.
### Postrelease Patch
1. **Branch Setup**: Checkout and update the release branch:
git checkout release-.
git pull origin release-.
2. **Patch Development**: Develop and test patch against branch. Add Towncrier entry and commit changes.
3. **Pre-Patch Validation**: Run quality checks to catch issues early:
hatch --env develop run linters
**Important**: Fix any linting errors before proceeding.
4. **Version Bump**: Bump to patch version and commit:
hatch version patch
git commit -am "Version: $(hatch version)"
5. **Changelog Generation**: Run Towncrier to build patch changelog:
hatch --env develop run towncrier build --keep --version $(hatch version)
git commit -am "Update changelog for v$(hatch version)."
6. **Patch Tag**: Create signed patch tag:
git tag -m "" v$(hatch version)
7. **Push Patch**: Push release branch and tag to upstream:
git push origin release-.
git push --tags
8. **Monitor Release**: Wait for the release workflow to complete successfully. Check the GitHub Actions tab to monitor progress.
9. **Post-Release Cleanup**: Clean up news fragments and push:
git rm .auxiliary/data/towncrier/*.rst
git commit -m "Clean up news fragments."
git push origin release-.
10. **Master Integration**: Cherry-pick patch commits back to `master`:
git checkout master
git pull origin master
git cherry-pick
git cherry-pick
git cherry-pick
git push origin master
Use `git log --oneline` on the release branch to identify commit hashes. Resolve any conflicts as necessary during cherry-picking.
## Changelog Entries
The project uses [Towncrier](https://towncrier.readthedocs.io/en/stable/) to manage its changelog. When making changes that should be noted in the changelog, add a file ("fragment") to the `.auxiliary/data/towncrier` directory with of `..rst`, for changes with a Github issue, or `+.<type>.rst`, for changes without an associated issue number.
The entries will be collected and organized when a release is made, as described in the release process sections above.
<a id="available-types"></a>
### Available Types
- `enhance`: features and other improvements (documentation, platform support, etc...)
- `notify`: deprecations and other notices
- `remove`: removals of feature or platform support
- `repair`: bug fixes
<a id="format"></a>
### Format
The file should contain a concise description of the change written in present tense. For example:
``` rst
Add support for immutable module reclassification.
```
The description should:
- Start with a capital letter.
- End with a period.
- For multi-component or multi-faceted projects, a topic followed by colon may be used to introduce the content. (E.g., "Github Actions: ", "Copier Template: ").
- Use present tense verbs in the imperative/subjunctive mood (e.g., "Add", "Fix", "Update") or simple noun phrases (e.g., "Support for \<x\>") in the introductory sentence.
- If explanatory content is necessary, then it may be provided in the indicative mood using whatever verb tense is most natural to provide historical context or other rationale.
- Focus on the what and why, not the how.
- Be understandable by users, not just developers.
- Acknowledge contributors.
<a id="examples"></a>
### Examples
Enhance:
``` rst
Improve release process documentation with Towncrier details.
```
Enhance:
``` rst
Add recursive module reclassification support.
```
Enhance:
``` rst
Support for Python 3.13.
```
Notice:
``` rst
Deprecate ``OvergeneralException``. Package now raises more specific
exceptions.
```
Remove:
``` rst
Remove deprecated ``make_immutable`` function.
```
Repair:
``` rst
Fix attribute visibility in immutable modules.
```