Release Process#

This page outlines the process for creating a new Fairlearn release. The following steps assume git remote’s origin points to fairlearn/fairlearn.

Ensure the maintainers listed in scripts/generate_maintainers_table.py are up to date. Run the command below from the repository root directory:
```
python scripts/generate_maintainers_table.py
```
If the generated file docs/about/maintainers.rst does not change you can proceed with the next step. Otherwise, create a PR to update the generated maintainers file on the main branch. Proceed only when the PR is merged.
Check the docs/user_guide/installation_and_version_guide for a file related to the release. Make sure formatting and contents are correct and create a summary of the highlights at the top of the file. Create a PR for this and merge it before proceeding.
If this is a non-patch release:
1. Create a new branch:
  git checkout -b release/v<x.y>.X
2. Push the branch to GitHub:
  git push -u origin release/v<x.y>.X
  You may need to temporarily add an exception to the branch protection rules by adding a new branch protection rule for release/v<x.y>.X.
On the release branch, create a PR to update the version in __init__.py to x.y.z (where z=0 for the first release from a branch)
Merge that PR.
Run the Release Wheel workflow on GitHub

Note

Ensure that you have selected the correct release branch. Immediately after building, the workflow runs uv run --no-project --with twine twine check --strict dist/* on both the wheel and source distribution. This metadata preflight rejects invalid README reStructuredText and missing metadata before the test matrix starts or the publishing artifact is uploaded. Fix any reported errors or warnings rather than changing the README content type or bypassing validation. The workflow tests the exact wheel built from that branch with stable dependencies only. It removes the checked-out Fairlearn package directory before installing the wheel so tests cannot accidentally import the source tree instead. Before publishing, it verifies the installed wheel’s origin, package contents, and version, and runs the tests including OpenML dataset downloads. The expected source version is passed from the build job to the test jobs as a job output, separate from the publishing artifact. If an OpenML test reports an invalid-cache warning, inspect the preceding exception in the full job log: a dataset parser error can also trigger scikit-learn’s cache retry warning.

Publishing currently authenticates with PYPI_API_TOKEN, so provenance attestations are disabled. To switch to PyPI Trusted Publishing, first register fairlearn/fairlearn and release-wheel.yml as a trusted publisher on PyPI. Then grant id-token: write to the release-wheel job and remove its password input and attestations: false override.

On the release branch, place an annotated tag:

git tag -a v<x.y.z> -m "v<x.y.z> release"

Push the tag to GitHub:
git push origin v<x.y.z>
On GitHub’s release page, draft a new release. Choose the new tag, title the release v<x.y.z>, and post the changes from the release file within docs/user_guide/installation_and_version_guide into the description, then hit “publish”.
On the main branch, create a PR to:
1. Update the version in __init__.py to x.y+1.z.dev0
2. Update the version in docs/static_landing_page/js/landing_page.js so that all the links point to the new release
3. Update the docs/_static/versions.json file
4. Create a new file vx.y+1.z.rst in docs/user_guide/installation_and_version_guide

Note

Make sure to add a note to the PR: “Do not merge until the release is completed. Otherwise a new website will be published that points to the new version which doesn’t exist yet.”

Merge the PR.