Release Guide¶

Welcome to the frozenlist Release Guide!

This page contains information on how to release a new version of frozenlist using the automated Continuous Delivery pipeline.

Tip

The intended audience for this document is maintainers and core contributors.

Pre-release activities¶

Check if there are any open Pull Requests that could be desired in the upcoming release. If there are any — merge them. If some are incomplete, try to get them ready. Don’t forget to review the enclosed change notes per our guidelines.
Visually inspect the draft section of the Changelog page. Make sure the content looks consistent, uses the same writing style, targets the end-users and adheres to our documented guidelines. Most of the changelog sections will typically use the past tense or another way to relay the effect of the changes for the users, since the previous release. It should not target core contributors as the information they are normally interested in is already present in the Git history. Update the changelog fragments if you see any problems with this changelog section.
Optionally, test the previously published nightlies, that are available through GitHub Actions CI/CD artifacts, locally.
If you are satisfied with the above, inspect the changelog section categories in the draft. Presence of the breaking changes or features will hint you what version number segment to bump for the release.
Update the hardcoded version string in frozenlist/__init__.py. Generate a new changelog from the fragments, and commit it along with the fragments removal and the Python module changes. Use the following commands, don’t prepend a leading-v before the version number. Just use the raw version number as per PEP 440.
```
[dir:frozenlist] $ frozenlist/__init__.py
[dir:frozenlist] $ python -m towncrier build \
                     -- --version 'VERSION_WITHOUT_LEADING_V'
[dir:frozenlist] $ git commit -v CHANGES{.rst,/} frozenlist/__init__.py
```

The release stage¶

Tag the commit with version and changelog changes, created during the preparation stage. If possible, make it GPG-signed. Prepend a leading v before the version number for the tag name. Add an extra sentence describing the release contents, in a few words.

[dir:frozenlist] $ git tag \
                     -s 'VERSION_WITH_LEADING_V' \
                     -m 'VERSION_WITH_LEADING_V' \
                     -m 'This release does X and Y.'

Push that tag to the upstream repository, which origin is considered to be in the example below.
```
[dir:frozenlist] $ git push origin 'VERSION_WITH_LEADING_V'
```
You can open the GitHub Actions CI/CD workflow page in your web browser to monitor the progress. But generally, you don’t need to babysit the CI.
Check that web page or your email inbox for the notification with an approval request. GitHub will send it when it reaches the final “publishing” job.
Approve the deployment and wait for the CD workflow to complete.
Verify that the following things got created: - a PyPI release - a Git tag - a GitHub Releases page
Tell everyone you released a new version of frozenlist :) Depending on your mental capacity and the burnout stage, you are encouraged to post the updates in issues asking for the next release, contributed PRs, Bluesky, Twitter etc. You can also call out prominent contributors and thank them!