Release Procedure

The following procedures gives a short overview of what steps are needed to create a new release.

Prepare your environment

Create your API tokens:
1. From the PyPI test server.
2. From the official PyPI server.
3. Save both tokens it in a safe place like your password manager.

Create a file ~/.pypirc with file mode 0600 and the following minimal content:

# Protect the file with chmod 0600 ~/.pypirc
[distutils]
index-servers =
     test-semver
     semver

[test-semver]
repository = https://test.pypi.org/legacy/
username = __token__
password = <YOUR_TEST_API_TOKEN>

[semver]
repository = https://pypi.org/legacy/
username = __token__
password = <YOUR_API_TOKEN>

Install uv as shown in Astral's Installing uv documentation.
Update the project's environment:
```
uv sync --group devel
```
Activate your environment:
```
source .venv/bin/activate
```

Prepare the Release

Create a new branch release/<VERSION>.
If one or several supported Python versions have been removed or added, verify that the following files have been updated:
- pyproject.toml (look into the key project.requires-python and project.classifiers)
- tox.ini
- .git/workflows/pythonpackage.yml
- CITATION.cff
Verify that:
- the version has been updated and follow https://semver.org:
  - src/semver/__about__.py
  - docs/usage/semver-version.rst
- all issues for a new release are closed: https://github.com/python-semver/python-semver/issues.
- all pull requests that should be included in this release are merged: https://github.com/python-semver/python-semver/pulls.
- continuous integration for latest build was passing: https://github.com/python-semver/python-semver/actions.
Add eventually new contributor(s) to CONTRIBUTORS.
Create the changelog:
1. Check if all changelog entries are created. If some are missing, create them.
2. Show the new draft CHANGELOG entry for the latest release with:
```
uvx tox r -e changelog
```
3. Check the output. If you are not happy, update the files in the changelog.d/ directory. If everything is okay, build the new CHANGELOG with:
```
uvx tox r -e changelog -- build
```
Build the documentation and check the output:
```
uvx tox r -e docs
```
Commit all changes, push, and create a pull request.

Create the New Release

Ensure that long description (README.rst) can be correctly rendered by Pypi using uvx restview -b README.rst
Clean up your local Git repository. Be careful, as it will remove all files which are not versioned by Git:
```
git clean -xfd
```
Before you create your distribution files, clean the directory too:
```
rm dist/*
```
Create the distribution files (wheel and source):
```
uvx tox r -e prepare-dist
```
Upload the wheel and source to TestPyPI first:
```
twine upload --verbose --repository test-semver dist/*
```
(Normally you would do it with uv publish, but for some unknown reason it didn't work for me.)
Check if everything is okay with the wheel. Check also the web site https://test.pypi.org/project/<VERSION>/

Finish the release

If everything looks fine, merge the pull request.

Upload to PyPI:

$ git clean -xfd
$ tox r -e prepare-dist
$ twine upload --verbose --repository semver dist/*

Go to https://pypi.org/project/semver/ to verify that new version is online and the page is rendered correctly.
Create a tag:
```
git tag -a x.y.z
```
It's recommended to use the generated Tox output from the Changelog.
Push the tag:
```
git push origin x.y.z
```
In GitHub Release page document the new release. Select the tag from the last step and copy the content of the tag description into the release description.
Announce it in https://github.com/python-semver/python-semver/discussions/categories/announcements.

You're done! Celebrate!

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!