Releases¶

The project follows semantic versioning 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 linters
hatch --env develop run testers
hatch --env develop run docsgen

Also, ensure that at least one news fragment exists under .auxiliary/data/towncrier.

Initial Release Candidate¶

Branch Setup: Checkout master branch and ensure it’s up to date:
```
git checkout master
git pull origin master
```
Create Release Branch: Checkout new release branch:
```
git checkout -b release-<major>.<minor>
```

Version Bump: Bump alpha to release candidate and commit:

hatch version rc
git commit -am "Version: $(hatch version)"

Tag Release Candidate:

git tag -m "Release candidate v$(hatch version)." v$(hatch version)

Push Branch and Tag: Push release branch and tag to upstream:

git push -u origin release-<major>.<minor>
git push --tags

Setup Next Development Cycle: Return to master and prepare for next version:

git checkout master
hatch version minor,alpha
git commit -am "Start development for v$(hatch version | sed 's/a[0-9]*$//')."
git tag -m "Start development for v$(hatch version | sed 's/a[0-9]*$//')." i$(hatch version | sed 's/a[0-9]*$//')
git push origin master --tags

Final Release¶

Branch Setup: Checkout and update the release branch:

git checkout release-<major>.<minor>
git pull origin release-<major>.<minor>

Version Finalization: Bump release candidate to final release:

hatch version release
git commit -am "Version: $(hatch version)"

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)."

Release Tag: Create signed release tag:

git tag -m "<description>" v$(hatch version)

Push Release: Push release branch and tag to upstream:

git push origin release-<major>.<minor>
git push --tags

Monitor Release: Wait for the release workflow to complete successfully. Check the GitHub Actions tab to monitor progress.

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-<major>.<minor>

Master Integration: Cherry-pick release commits back to master:

git checkout master
git pull origin master
git cherry-pick <changelog-commit-hash>
git cherry-pick <cleanup-commit-hash>
git push origin master

Use git log --oneline on the release branch to identify commit hashes.

Postrelease Patch¶

Branch Setup: Checkout and update the release branch:

git checkout release-<major>.<minor>
git pull origin release-<major>.<minor>

Patch Development: Develop and test patch against branch. Add Towncrier entry and commit changes.
Pre-Patch Validation: Run quality checks to catch issues early:
```
hatch --env develop run linters
```
Important: Fix any linting errors before proceeding.

Version Bump: Bump to patch version and commit:

hatch version patch
git commit -am "Version: $(hatch version)"

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)."

Patch Tag: Create signed patch tag:

git tag -m "<description>" v$(hatch version)

Push Patch: Push release branch and tag to upstream:

git push origin release-<major>.<minor>
git push --tags

Monitor Release: Wait for the release workflow to complete successfully. Check the GitHub Actions tab to monitor progress.

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-<major>.<minor>

Master Integration: Cherry-pick patch commits back to master:

git checkout master
git pull origin master
git cherry-pick <patch-commit-hash>
git cherry-pick <changelog-commit-hash>
git cherry-pick <cleanup-commit-hash>
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 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 <issue_number>.<type>.rst, for changes with a Github issue, or +<title>.<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.

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

Format¶

The file should contain a concise description of the change written in present tense. For example:

.auxiliary/data/towncrier/+immutable-modules.enhance.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.

Examples¶

Enhance:

.auxiliary/data/towncrier/457.enhance.rst¶

Improve release process documentation with Towncrier details.

Enhance:

.auxiliary/data/towncrier/458.enhance.rst¶

Add recursive module reclassification support.

Enhance:

.auxiliary/data/towncrier/459.enhance.rst¶

Support for Python 3.13.

Notice:

.auxiliary/data/towncrier/+exceptions.notify.rst¶

Deprecate ``OvergeneralException``. Package now raises more specific
exceptions.

Remove:

.auxiliary/data/towncrier/460.remove.rst¶

Remove deprecated ``make_immutable`` function.

Repair:

.auxiliary/data/towncrier/456.repair.rst¶

Fix attribute visibility in immutable modules.