Releases¶

The project follows semantic versioning for releases.

Release Process¶

Initial Release Candidate¶

Checkout master branch.
Pull from upstream to ensure all changes have been synced.
Checkout new release branch: release-<major>.<minor>.
Bump alpha to release candidate. Commit.
```
hatch --env develop version rc
```
Tag.
```
git tag v${rc_version}
```
Push release branch and tag to upstream with tracking enabled.
Checkout master branch.
Bump alpha to next minor version on master branch. Commit.
```
hatch --env develop version minor,alpha
```
Tag start of development for next release.
git tag i${next_release_version}

Release¶

Checkout release branch.
Bump release candidate to release. Commit.
```
hatch --env develop version release
```

Run Towncrier. Commit.

hatch --env develop run towncrier build --keep --version ${release_version}

Tag.
```
git tag v${release_version}
```
Push release branch and tag to upstream.
Wait for the release workflow to complete successfully.

Clean up news fragments to prevent recycling in future releases. Commit.

git rm documentation/towncrier/*.rst
git commit -m "Clean up news fragments."

Push cleanup commit to upstream.
Cherry-pick Towncrier commits back to master branch.

Postrelease Patch¶

Checkout release branch.
Develop and test patch against branch. Add Towncrier entry. Commit.
Bump release to patch or increment patch number. Commit.
```
hatch --env develop version patch
```

Run Towncrier. Commit.

hatch --env develop run towncrier build --keep --version ${patch_version}

Tag.
```
git tag v${patch_version}
```
Push release branch and tag to upstream.
Wait for the release workflow to complete successfully.

Clean up news fragments to prevent recycling in future releases. Commit.

git rm documentation/towncrier/*.rst
git commit -m "Clean up news fragments."

Push cleanup commit to upstream.
Cherry-pick patch and Towncrier commits back to master branch, resolving conflicts as necessary.

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 documentation/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¶

bugfix: For bug fixes
docs: For documentation improvements
feature: For new features
platform: For changes to supported platforms
removal: For deprecations and removals

Format¶

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

documentation/towncrier/+immutable-modules.feature.rst¶

Add support for immutable module reclassification.

The description should:

Start with a capital letter
End with a period
Use present tense (e.g., “Add”, “Fix”, “Update”)
Focus on the what and why, not the how
Be understandable by users, not just developers

Examples¶

Bug Fix:

documentation/towncrier/456.bugfix.rst¶

Fix attribute visibility in immutable modules.

Documentation:

documentation/towncrier/457.docs.rst¶

Improve release process documentation with Towncrier details.

Feature:

documentation/towncrier/458.feature.rst¶

Add recursive module reclassification support.

Platform:

documentation/towncrier/459.platform.rst¶

Add support for Python 3.13.

Removal:

documentation/towncrier/460.removal.rst¶

Remove deprecated ``make_immutable`` function.