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.mdand the docs to version the latest changes
Remove any empty sections for the current release
Add a new empty template for the next release (template below)
Example PR: #2616
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)
CHANGES.mdand 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.
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.
Use the following template for a clean changelog after the release:
## Unreleased ### Highlights <!-- Include any especially major or disruptive changes here --> ### Style <!-- Changes that affect Black's stable style --> ### Preview style <!-- Changes that affect Black's preview style --> ### _Blackd_ <!-- Changes to blackd --> ### Configuration <!-- Changes to how Black can be configured --> ### Documentation <!-- Major changes to documentation and policies. Small docs changes don't need a changelog entry. --> ### Integrations <!-- For example, Docker, GitHub Actions, pre-commit, editors --> ### Output <!-- Changes to Black's terminal output and error messages --> ### Packaging <!-- Changes to how Black is packaged, such as dependency requirements --> ### Parser <!-- Changes to the parser or to version autodetection --> ### Performance <!-- Changes that improve Black's performance. -->
All Blacks’s automation workflows use GitHub Actions. All workflows are therefore
.yml files in the
.github/workflows directory of the Black
Below are descriptions of our release workflows.
This workflow uses the QEMU powered
buildx feature of docker to upload a
x86_64 build of the official Black docker image™.
Currently this workflow uses an API Token associated with @cooperlees account
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 😢).
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.
Tag moving process#
From a rebased
git tag -f stable VERSION_TAG
git tag -f stable 21.5b1
git push --tags -f