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 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 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 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 .auxiliary/data/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 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 .auxiliary/data/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 .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.