docs/contributing/release_process.md

   1 # Release process
   2
   3 _Black_ has had a lot of work automating its release process. This document sets out to
   4 explain what everything does and how to release _Black_ using said automation.
   5
   6 ## Cutting a Release
   7
   8 To cut a release, you must be a _Black_ maintainer with `GitHub Release` creation
   9 access. Using this access, the release process is:
  10
  11 1. Cut a new PR editing `CHANGES.md` to version the latest changes
  12    1. Example PR: https://github.com/psf/black/pull/2192
  13    2. Example title: `Update CHANGES.md for XX.X release`
  14 2. Once the release PR is merged ensure all CI passes
  15    1. If not, ensure there is an Issue open for the cause of failing CI (generally we'd
  16       want this fixed before cutting a release)
  17 3. Open `CHANGES.md` and copy the _raw markdown_ of the latest changes to use in the
  18    description of the GitHub Release.
  19 4. Go and [cut a release](https://github.com/psf/black/releases) using the GitHub UI so
  20    that all workflows noted below are triggered.
  21    1. The release version and tag should be the [CalVer](https://calver.org) version
  22       _Black_ used for the current release e.g. `21.6` / `21.5b1`
  23    2. _Black_ uses [setuptools scm](https://pypi.org/project/setuptools-scm/) to pull
  24       the current version for the package builds and release.
  25 5. Once the release is cut, you're basically done. It's a good practice to go and watch
  26    to make sure all the [GitHub Actions](https://github.com/psf/black/actions) pass,
  27    although you should receive an email to your registered GitHub email address should
  28    one fail.
  29    1. You should see all the release workflows and lint/unittests workflows running on
  30       the new tag in the Actions UI
  31
  32 If anything fails, please go read the respective action's log output and configuration
  33 file to reverse engineer your way to a fix/soluton.
  34
  35 ## Release workflows
  36
  37 All _Blacks_'s automation workflows use GitHub Actions. All workflows are therefore
  38 configured using `.yml` files in the `.github/workflows` directory of the _Black_
  39 repository.
  40
  41 Below are descriptions of our release workflows.
  42
  43 ### Docker
  44
  45 This workflow uses the QEMU powered `buildx` feature of docker to upload a `arm64` and
  46 `amd64`/`x86_64` build of the official _Black_ docker image™.
  47
  48 - Currently this workflow uses an API Token associated with @cooperlees account
  49
  50 ### pypi_upload
  51
  52 This workflow builds a Python
  53 [sdist](https://docs.python.org/3/distutils/sourcedist.html) and
  54 [wheel](https://pythonwheels.com) using the latest
  55 [setuptools](https://pypi.org/project/setuptools/) and
  56 [wheel](https://pypi.org/project/wheel/) modules.
  57
  58 It will then use [twine](https://pypi.org/project/twine/) to upload both release formats
  59 to PyPI for general downloading of the _Black_ Python package. This is where
  60 [pip](https://pypi.org/project/pip/) looks by default.
  61
  62 - Currently this workflow uses an API token associated with @ambv's PyPI account
  63
  64 ### Upload self-contained binaries
  65
  66 This workflow builds self-contained binaries for multiple platforms. This allows people
  67 to download the executable for their platform and run _Black_ without a
  68 [Python Runtime](https://wiki.python.org/moin/PythonImplementations) installed.
  69
  70 The created binaries are attached/stored on the associated
  71 [GitHub Release](https://github.com/psf/black/releases) for download over _IPv4 only_
  72 (GitHub still does not have IPv6 access 😢).
  73
  74 ## Moving the `stable` tag
  75
  76 _Black_ provides a stable tag for people who want to move along as _Black_ developers
  77 deem the newest version reliable. Here the _Black_ developers will move once the release
  78 has been problem free for at least ~24 hours from release. Given the large _Black_
  79 userbase we hear about bad bugs quickly. We do strive to continually improve our CI too.
  80
  81 ### Tag moving process
  82
  83 #### stable
  84
  85 From a rebased `main` checkout:
  86
  87 1. `git tag -f stable VERSION_TAG`
  88    1. e.g. `git tag -f stable 21.5b1`
  89 1. `git push --tags -f`