Release process¶
Black has had a lot of work automating its release process. This document sets out to explain what everything does and how to release Black using said automation.
Cutting a Release¶
To cut a release, you must be a Black maintainer with GitHub Release
creation
access. Using this access, the release process is:
Cut a new PR editing
CHANGES.md
to version the latest changesExample PR: https://github.com/psf/black/pull/2192
Example title:
Update CHANGES.md for XX.X release
Once the release PR is merged ensure all CI passes
If not, ensure there is an Issue open for the cause of failing CI (generally we’d want this fixed before cutting a release)
Open
CHANGES.md
and copy the raw markdown of the latest changes to use in the description of the GitHub Release.Go and cut a release using the GitHub UI so that all workflows noted below are triggered.
The release version and tag should be the CalVer version Black used for the current release e.g.
21.6
/21.5b1
Black uses setuptools scm to pull the current version for the package builds and release.
Once the release is cut, you’re basically done. It’s a good practice to go and watch to make sure all the GitHub Actions pass, although you should receive an email to your registered GitHub email address should one fail.
You should see all the release workflows and lint/unittests workflows running on the new tag in the Actions UI
If anything fails, please go read the respective action’s log output and configuration file to reverse engineer your way to a fix/soluton.
Release workflows¶
All Blacks’s automation workflows use GitHub Actions. All workflows are therefore
configured using .yml
files in the .github/workflows
directory of the Black
repository.
Below are descriptions of our release workflows.
Docker¶
This workflow uses the QEMU powered buildx
feature of docker to upload a arm64
and
amd64
/x86_64
build of the official Black docker image™.
Currently this workflow uses an API Token associated with @cooperlees account
pypi_upload¶
This workflow builds a Python sdist and wheel using the latest setuptools and wheel modules.
It will then use twine to upload both release formats to PyPI for general downloading of the Black Python package. This is where pip looks by default.
Currently this workflow uses an API token associated with @ambv’s PyPI account
Upload self-contained binaries¶
This workflow builds self-contained binaries for multiple platforms. This allows people to download the executable for their platform and run Black without a Python Runtime installed.
The created binaries are attached/stored on the associated GitHub Release for download over IPv4 only (GitHub still does not have IPv6 access 😢).
Moving the stable
tag¶
Black provides a stable tag for people who want to move along as Black developers deem the newest version reliable. Here the Black developers will move once the release has been problem free for at least ~24 hours from release. Given the large Black userbase we hear about bad bugs quickly. We do strive to continually improve our CI too.