docs/contributing/release_process.md

   1 # Release process
   2
   3 _Black_ has had a lot of work done into standardizing and automating its release
   4 process. This document sets out to explain how everything works and how to release
   5 _Black_ using said automation.
   6
   7 ## Release cadence
   8
   9 **We aim to release whatever is on `main` every 1-2 months.** This ensures merged
  10 improvements and bugfixes are shipped to users reasonably quickly, while not massively
  11 fracturing the user-base with too many versions. This also keeps the workload on
  12 maintainers consistent and predictable.
  13
  14 If there's not much new on `main` to justify a release, it's acceptable to skip a
  15 month's release. Ideally January releases should not be skipped because as per our
  16 [stability policy](labels/stability-policy), the first release in a new calendar year
  17 may make changes to the _stable_ style. While the policy applies to the first release
  18 (instead of only January releases), confining changes to the stable style to January
  19 will keep things predictable (and nicer) for users.
  20
  21 Unless there is a serious regression or bug that requires immediate patching, **there
  22 should not be more than one release per month**. While version numbers are cheap,
  23 releases require a maintainer to both commit to do the actual cutting of a release, but
  24 also to be able to deal with the potential fallout post-release. Releasing more
  25 frequently than monthly nets rapidly diminishing returns.
  26
  27 ## Cutting a release
  28
  29 **You must have `write` permissions for the _Black_ repository to cut a release.**
  30
  31 The 10,000 foot view of the release process is that you prepare a release PR and then
  32 publish a [GitHub Release]. This triggers [release automation](#release-workflows) that
  33 builds all release artifacts and publishes them to the various platforms we publish to.
  34
  35 To cut a release:
  36
  37 1. Determine the release's version number
  38    - **_Black_ follows the [CalVer] versioning standard using the `YY.M.N` format**
  39      - So unless there already has been a release during this month, `N` should be `0`
  40    - Example: the first release in January, 2022 → `22.1.0`
  41 1. File a PR editing `CHANGES.md` and the docs to version the latest changes
  42    1. Replace the `## Unreleased` header with the version number
  43    1. Remove any empty sections for the current release
  44    1. (_optional_) Read through and copy-edit the changelog (eg. by moving entries,
  45       fixing typos, or rephrasing entries)
  46    1. Double-check that no changelog entries since the last release were put in the
  47       wrong section (e.g., run `git diff <last release> CHANGES.md`)
  48    1. Add a new empty template for the next release above
  49       ([template below](#changelog-template))
  50    1. Update references to the latest version in
  51       {doc}`/integrations/source_version_control` and
  52       {doc}`/usage_and_configuration/the_basics`
  53    - Example PR: [GH-3139]
  54 1. Once the release PR is merged, wait until all CI passes
  55    - If CI does not pass, **stop** and investigate the failure(s) as generally we'd want
  56      to fix failing CI before cutting a release
  57 1. [Draft a new GitHub Release][new-release]
  58    1. Click `Choose a tag` and type in the version number, then select the
  59       `Create new tag: YY.M.N on publish` option that appears
  60    1. Verify that the new tag targets the `main` branch
  61    1. You can leave the release title blank, GitHub will default to the tag name
  62    1. Copy and paste the _raw changelog Markdown_ for the current release into the
  63       description box
  64 1. Publish the GitHub Release, triggering [release automation](#release-workflows) that
  65    will handle the rest
  66 1. At this point, you're basically done. It's good practice to go and [watch and verify
  67    that all the release workflows pass][black-actions], although you will receive a
  68    GitHub notification should something fail.
  69    - If something fails, don't panic. Please go read the respective workflow's logs and
  70      configuration file to reverse-engineer your way to a fix/solution.
  71
  72 Congratulations! You've successfully cut a new release of _Black_. Go and stand up and
  73 take a break, you deserve it.
  74
  75 ```{important}
  76 Once the release artifacts reach PyPI, you may see new issues being filed indicating
  77 regressions. While regressions are not great, they don't automatically mean a hotfix
  78 release is warranted. Unless the regressions are serious and impact many users, a hotfix
  79 release is probably unnecessary.
  80
  81 In the end, use your best judgement and ask other maintainers for their thoughts.
  82 ```
  83
  84 ### Changelog template
  85
  86 Use the following template for a clean changelog after the release:
  87
  88 ```
  89 ## Unreleased
  90
  91 ### Highlights
  92
  93 <!-- Include any especially major or disruptive changes here -->
  94
  95 ### Stable style
  96
  97 <!-- Changes that affect Black's stable style -->
  98
  99 ### Preview style
 100
 101 <!-- Changes that affect Black's preview style -->
 102
 103 ### Configuration
 104
 105 <!-- Changes to how Black can be configured -->
 106
 107 ### Packaging
 108
 109 <!-- Changes to how Black is packaged, such as dependency requirements -->
 110
 111 ### Parser
 112
 113 <!-- Changes to the parser or to version autodetection -->
 114
 115 ### Performance
 116
 117 <!-- Changes that improve Black's performance. -->
 118
 119 ### Output
 120
 121 <!-- Changes to Black's terminal output and error messages -->
 122
 123 ### _Blackd_
 124
 125 <!-- Changes to blackd -->
 126
 127 ### Integrations
 128
 129 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->
 130
 131 ### Documentation
 132
 133 <!-- Major changes to documentation and policies. Small docs changes
 134      don't need a changelog entry. -->
 135 ```
 136
 137 ## Release workflows
 138
 139 All of _Black_'s release automation uses [GitHub Actions]. All workflows are therefore
 140 configured using YAML files in the `.github/workflows` directory of the _Black_
 141 repository.
 142
 143 They are triggered by the publication of a [GitHub Release].
 144
 145 Below are descriptions of our release workflows.
 146
 147 ### Publish to PyPI
 148
 149 This is our main workflow. It builds an [sdist] and [wheels] to upload to PyPI where the
 150 vast majority of users will download Black from. It's divided into three job groups:
 151
 152 #### sdist + pure wheel
 153
 154 This single job builds the sdist and pure Python wheel (i.e., a wheel that only contains
 155 Python code) using [build] and then uploads them to PyPI using [twine]. These artifacts
 156 are general-purpose and can be used on basically any platform supported by Python.
 157
 158 #### mypyc wheels (…)
 159
 160 We use [mypyc] to compile _Black_ into a CPython C extension for significantly improved
 161 performance. Wheels built with mypyc are platform and Python version specific.
 162 [Supported platforms are documented in the FAQ](labels/mypyc-support).
 163
 164 These matrix jobs use [cibuildwheel] which handles the complicated task of building C
 165 extensions for many environments for us. Since building these wheels is slow, there are
 166 multiple mypyc wheels jobs (hence the term "matrix") that build for a specific platform
 167 (as noted in the job name in parentheses).
 168
 169 Like the previous job group, the built wheels are uploaded to PyPI using [twine].
 170
 171 #### Update stable branch
 172
 173 So this job doesn't _really_ belong here, but updating the `stable` branch after the
 174 other PyPI jobs pass (they must pass for this job to start) makes the most sense. This
 175 saves us from remembering to update the branch sometime after cutting the release.
 176
 177 - _Currently this workflow uses an API token associated with @ambv's PyPI account_
 178
 179 ### Publish executables
 180
 181 This workflow builds native executables for multiple platforms using [PyInstaller]. This
 182 allows people to download the executable for their platform and run _Black_ without a
 183 [Python runtime](https://wiki.python.org/moin/PythonImplementations) installed.
 184
 185 The created binaries are stored on the associated GitHub Release for download over _IPv4
 186 only_ (GitHub still does not have IPv6 access 😢).
 187
 188 ### docker
 189
 190 This workflow uses the QEMU powered `buildx` feature of Docker to upload an `arm64` and
 191 `amd64`/`x86_64` build of the official _Black_ Docker image™.
 192
 193 - _Currently this workflow uses an API Token associated with @cooperlees account_
 194
 195 ```{note}
 196 This also runs on each push to `main`.
 197 ```
 198
 199 [black-actions]: https://github.com/psf/black/actions
 200 [build]: https://pypa-build.readthedocs.io/
 201 [calver]: https://calver.org
 202 [cibuildwheel]: https://cibuildwheel.readthedocs.io/
 203 [gh-3139]: https://github.com/psf/black/pull/3139
 204 [github actions]: https://github.com/features/actions
 205 [github release]: https://github.com/psf/black/releases
 206 [new-release]: https://github.com/psf/black/releases/new
 207 [mypyc]: https://mypyc.readthedocs.io/
 208 [mypyc-platform-support]:
 209   /faq.html#what-is-compiled-yes-no-all-about-in-the-version-output
 210 [pyinstaller]: https://www.pyinstaller.org/
 211 [sdist]:
 212   https://packaging.python.org/en/latest/glossary/#term-Source-Distribution-or-sdist
 213 [twine]: https://github.com/features/actions
 214 [wheels]: https://packaging.python.org/en/latest/glossary/#term-Wheel