Black's release process has been standardized and automated. This document explains what to expect and how to release Black using said automation.
We aim to release whatever is on main every 1-2 months. This ensures merged improvements and bugfixes are shipped to users reasonably quickly, while not massively fracturing the userbase with too many versions. This also keeps the workload on maintainers consistent and predictable.
If there‘s not much new on main to justify a release, it’s acceptable to skip a month's release. Ideally January releases should not be skipped, since the first release in a new calendar year may make changes to the stable style, as per our stability policy. While the policy applies to the first release (instead of only January releases), confining changes to the stable style to January will keep things predictable (and nicer) for users.
Unless there is a serious regression or bug that requires immediate patching, there should not be more than one release per month. While version numbers are cheap, releases require a maintainer to commit not only to the actual cutting of a release, but also to deal with the potential fallout post-release. Releasing more frequently than monthly nets rapidly diminishing returns.
You must have write permissions for the Black repository to cut a release.
The 10,000-foot view of the release process is that you trigger a workflow to create a PR automating the release chores. Then, merge it, triggering release automation that builds all release artifacts and publishes them to the various platforms we publish to.
Start here for prereleases as well. Run “prepare release” against main as described before stabilizing preview features or making other prerelease changes. The appropriate times to do those are included in the instructions below.
To cut a release:
Run the “prepare release” workflow. Make sure to leave the main branch selected. This will create a PR automating most of the needed changes.
Version_Override input empty.YY.M.N format.N should be 0.26.1.0.YY.MMaN format.N at 1 (not 0).26.1a1, but Version_Override should be set to 26.1.0.You will be auto-assigned to the created PR. Check the changelog diff in the description and copyedit CHANGES.md. The CI will update it after each push, so double-check it again before you merge. Things to check include:
If you're releasing a prerelease or major version, commit the changes unique to it to the PR branch. If you make any changes that should have a changelog entry, remember to add one!
If you're releasing a major version (or a prerelease for one), there are some specific additional changes to make at this point:
wcwidth to the latest version and run scripts/make_width_table.pyWait for CI to pass on the PR, and fix any failures.
To cut a stable release, merge the PR once everything looks good. If you‘re cutting a prerelease, do not merge it, and instead run the “cut release” workflow manually. Make sure to select the ci/prepare-release/<version> branch, where <version> is the stable version you’re preparing. You can release multiple prereleases from the same PR by running “cut release” multiple times after any desired changes.
Make sure CI passes. At this point, you‘re basically done, but it’s good practice to watch and verify that all the release workflows pass, though GitHub may notify you anyway if something fails.
main and rerun it manually with no issues. Again, run it on the main branch for stable releases or the ci/prepare-release/<version> branch for prereleases.Congratulations! You've successfully cut a new release of Black. Go stand up and take a break, you deserve it.
Once the release artifacts are published, you may see new issues being filed indicating regressions. While regressions are not great, they don't automatically mean a hotfix release is warranted. Unless the regressions are serious and impact many users, a hotfix release is probably unnecessary. In the end, use your best judgment and ask other maintainers for their thoughts.
All of Black's release automation uses GitHub Actions. All workflows are therefore configured using YAML files in the .github/workflows directory of the Black repository. They are triggered at various points in the release process detailed above.
This workflow is manually run as the first step in the release process. It handles many of the initial chores before releasing.
This job runs scripts/release.py to clean up CHANGES.md and bump most references to old Black versions, then creates a PR with the changes for your review. The PR creation is authenticated in order to trigger test CI.
_Currently this workflow uses a GitHub API token associated with @JelleZijlstra's account._
This job runs after create and after each subsequent push to the PR. It updates the changelog diff in the PR description.
This workflow runs when the changelog PR is merged (or when manually triggered, in the case of prereleases or reruns after a failure). It creates and publishes a release, which triggers the other release workflows, then completes final post-release chores.
This job determines if the release should be a prerelease (if the workflow is run on a branch other than main). It then creates a draft release for the next step.
These matrix jobs build native executables for multiple platforms using PyInstaller. This allows people to download the executable for their platform and run Black without a Python runtime installed.
The created binaries are stored on the associated draft GitHub Release for download. Note that we use GitHub's immutable releases, preventing assets or tags from being modified once the release is published as a security measure.
This job marks the release as published. This is authenticated in order to trigger further release automation. Then, only if the release was stable, it updates the stable branch by force pushing it to the most recent tag.
_Currently this workflow uses a GitHub API token associated with @JelleZijlstra's account._
This job opens a new PR to add the “Unreleased” section back to the changelog. The PR is not auto-merged to allow the releaser time to make sure all the release workflows succeed. The PR creation is authenticated in order to trigger test CI.
_Currently this workflow uses a GitHub API token associated with @JelleZijlstra's account._
This is our main workflow, triggered when the release is published. It builds an sdist and wheels to upload to PyPI, where the vast majority of users download Black from.
It also runs as a test dry run on each PR and push to main (without publishing anything to PyPI).
This single job builds the sdist and pure Python wheel (i.e., a wheel that only contains Python code) using Hatch. These artifacts are general-purpose and can be used on basically any platform supported by Python.
We use mypyc to compile Black into a CPython C extension for significantly improved performance. Wheels built with mypyc are platform and Python version specific. Supported platforms are documented in the FAQ.
These matrix jobs use cibuildwheel which handles the complicated task of building C extensions for many environments for us. It uses a matrix to build each platform in parallel (as noted in the job name in parentheses).
These jobs upload the built sdist and all wheels to PyPI using Trusted Publishing. This step does not run on PRs or pushes to main.
This workflow uses Docker Buildx to build and push arm64 and amd64/x86_64 builds of the official Black Docker image to Docker Hub.
This also runs on each push to main.
_Currently this workflow uses a Docker API token associated with @cooperlees's account._