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` and the docs to version the latest changes
  12    1. Remove any empty sections for the current release
  13    2. Add a new empty template for the next release (template below)
  14    3. Example PR: [#2616](https://github.com/psf/black/pull/2616)
  15    4. Example title: `Update CHANGES.md for XX.X release`
  16 2. Once the release PR is merged ensure all CI passes
  17    1. If not, ensure there is an Issue open for the cause of failing CI (generally we'd
  18       want this fixed before cutting a release)
  19 3. Open `CHANGES.md` and copy the _raw markdown_ of the latest changes to use in the
  20    description of the GitHub Release.
  21 4. Go and [cut a release](https://github.com/psf/black/releases) using the GitHub UI so
  22    that all workflows noted below are triggered.
  23    1. The release version and tag should be the [CalVer](https://calver.org) version
  24       _Black_ used for the current release e.g. `21.6` / `21.5b1`
  25    2. _Black_ uses [setuptools scm](https://pypi.org/project/setuptools-scm/) to pull
  26       the current version for the package builds and release.
  27 5. Once the release is cut, you're basically done. It's a good practice to go and watch
  28    to make sure all the [GitHub Actions](https://github.com/psf/black/actions) pass,
  29    although you should receive an email to your registered GitHub email address should
  30    one fail.
  31    1. You should see all the release workflows and lint/unittests workflows running on
  32       the new tag in the Actions UI
  33
  34 If anything fails, please go read the respective action's log output and configuration
  35 file to reverse engineer your way to a fix/soluton.
  36
  37 ## Changelog template
  38
  39 Use the following template for a clean changelog after the release:
  40
  41 ```
  42 ## Unreleased
  43
  44 ### Highlights
  45
  46 <!-- Include any especially major or disruptive changes here -->
  47
  48 ### Style
  49
  50 <!-- Changes that affect Black's stable style -->
  51
  52 ### Preview style
  53
  54 <!-- Changes that affect Black's preview style -->
  55
  56 ### _Blackd_
  57
  58 <!-- Changes to blackd -->
  59
  60 ### Configuration
  61
  62 <!-- Changes to how Black can be configured -->
  63
  64 ### Documentation
  65
  66 <!-- Major changes to documentation and policies. Small docs changes
  67      don't need a changelog entry. -->
  68
  69 ### Integrations
  70
  71 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->
  72
  73 ### Output
  74
  75 <!-- Changes to Black's terminal output and error messages -->
  76
  77 ### Packaging
  78
  79 <!-- Changes to how Black is packaged, such as dependency requirements -->
  80
  81 ### Parser
  82
  83 <!-- Changes to the parser or to version autodetection -->
  84
  85 ### Performance
  86
  87 <!-- Changes that improve Black's performance. -->
  88
  89 ```
  90
  91 ## Release workflows
  92
  93 All _Blacks_'s automation workflows use GitHub Actions. All workflows are therefore
  94 configured using `.yml` files in the `.github/workflows` directory of the _Black_
  95 repository.
  96
  97 Below are descriptions of our release workflows.
  98
  99 ### Docker
 100
 101 This workflow uses the QEMU powered `buildx` feature of docker to upload a `arm64` and
 102 `amd64`/`x86_64` build of the official _Black_ docker image™.
 103
 104 - Currently this workflow uses an API Token associated with @cooperlees account
 105
 106 ### pypi_upload
 107
 108 This workflow builds a Python
 109 [sdist](https://docs.python.org/3/distutils/sourcedist.html) and
 110 [wheel](https://pythonwheels.com) using the latest
 111 [setuptools](https://pypi.org/project/setuptools/) and
 112 [wheel](https://pypi.org/project/wheel/) modules.
 113
 114 It will then use [twine](https://pypi.org/project/twine/) to upload both release formats
 115 to PyPI for general downloading of the _Black_ Python package. This is where
 116 [pip](https://pypi.org/project/pip/) looks by default.
 117
 118 - Currently this workflow uses an API token associated with @ambv's PyPI account
 119
 120 ### Upload self-contained binaries
 121
 122 This workflow builds self-contained binaries for multiple platforms. This allows people
 123 to download the executable for their platform and run _Black_ without a
 124 [Python Runtime](https://wiki.python.org/moin/PythonImplementations) installed.
 125
 126 The created binaries are attached/stored on the associated
 127 [GitHub Release](https://github.com/psf/black/releases) for download over _IPv4 only_
 128 (GitHub still does not have IPv6 access 😢).
 129
 130 ## Moving the `stable` tag
 131
 132 _Black_ provides a stable tag for people who want to move along as _Black_ developers
 133 deem the newest version reliable. Here the _Black_ developers will move once the release
 134 has been problem free for at least ~24 hours from release. Given the large _Black_
 135 userbase we hear about bad bugs quickly. We do strive to continually improve our CI too.
 136
 137 ### Tag moving process
 138
 139 #### stable
 140
 141 From a rebased `main` checkout:
 142
 143 1. `git tag -f stable VERSION_TAG`
 144    1. e.g. `git tag -f stable 21.5b1`
 145 1. `git push --tags -f`