]> git.madduck.net Git - etc/vim.git/blob - docs/contributing/release_process.md

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

Bump furo from 2023.7.26 to 2023.8.19 in /docs + sphinx to 7.2.3 (#3848)
[etc/vim.git] / 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. Add a new empty template for the next release above
47       ([template below](#changelog-template))
48    1. Update references to the latest version in
49       {doc}`/integrations/source_version_control` and
50       {doc}`/usage_and_configuration/the_basics`
51    - Example PR: [GH-3139]
52 1. Once the release PR is merged, wait until all CI passes
53    - If CI does not pass, **stop** and investigate the failure(s) as generally we'd want
54      to fix failing CI before cutting a release
55 1. [Draft a new GitHub Release][new-release]
56    1. Click `Choose a tag` and type in the version number, then select the
57       `Create new tag: YY.M.N on publish` option that appears
58    1. Verify that the new tag targets the `main` branch
59    1. You can leave the release title blank, GitHub will default to the tag name
60    1. Copy and paste the _raw changelog Markdown_ for the current release into the
61       description box
62 1. Publish the GitHub Release, triggering [release automation](#release-workflows) that
63    will handle the rest
64 1. At this point, you're basically done. It's good practice to go and [watch and verify
65    that all the release workflows pass][black-actions], although you will receive a
66    GitHub notification should something fail.
67    - If something fails, don't panic. Please go read the respective workflow's logs and
68      configuration file to reverse-engineer your way to a fix/solution.
69
70 Congratulations! You've successfully cut a new release of _Black_. Go and stand up and
71 take a break, you deserve it.
72
73 ```{important}
74 Once the release artifacts reach PyPI, you may see new issues being filed indicating
75 regressions. While regressions are not great, they don't automatically mean a hotfix
76 release is warranted. Unless the regressions are serious and impact many users, a hotfix
77 release is probably unnecessary.
78
79 In the end, use your best judgement and ask other maintainers for their thoughts.
80 ```
81
82 ### Changelog template
83
84 Use the following template for a clean changelog after the release:
85
86 ```
87 ## Unreleased
88
89 ### Highlights
90
91 <!-- Include any especially major or disruptive changes here -->
92
93 ### Stable style
94
95 <!-- Changes that affect Black's stable style -->
96
97 ### Preview style
98
99 <!-- Changes that affect Black's preview style -->
100
101 ### Configuration
102
103 <!-- Changes to how Black can be configured -->
104
105 ### Packaging
106
107 <!-- Changes to how Black is packaged, such as dependency requirements -->
108
109 ### Parser
110
111 <!-- Changes to the parser or to version autodetection -->
112
113 ### Performance
114
115 <!-- Changes that improve Black's performance. -->
116
117 ### Output
118
119 <!-- Changes to Black's terminal output and error messages -->
120
121 ### _Blackd_
122
123 <!-- Changes to blackd -->
124
125 ### Integrations
126
127 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->
128
129 ### Documentation
130
131 <!-- Major changes to documentation and policies. Small docs changes
132      don't need a changelog entry. -->
133 ```
134
135 ## Release workflows
136
137 All of _Black_'s release automation uses [GitHub Actions]. All workflows are therefore
138 configured using YAML files in the `.github/workflows` directory of the _Black_
139 repository.
140
141 They are triggered by the publication of a [GitHub Release].
142
143 Below are descriptions of our release workflows.
144
145 ### Publish to PyPI
146
147 This is our main workflow. It builds an [sdist] and [wheels] to upload to PyPI where the
148 vast majority of users will download Black from. It's divided into three job groups:
149
150 #### sdist + pure wheel
151
152 This single job builds the sdist and pure Python wheel (i.e., a wheel that only contains
153 Python code) using [build] and then uploads them to PyPI using [twine]. These artifacts
154 are general-purpose and can be used on basically any platform supported by Python.
155
156 #### mypyc wheels (…)
157
158 We use [mypyc] to compile _Black_ into a CPython C extension for significantly improved
159 performance. Wheels built with mypyc are platform and Python version specific.
160 [Supported platforms are documented in the FAQ](labels/mypyc-support).
161
162 These matrix jobs use [cibuildwheel] which handles the complicated task of building C
163 extensions for many environments for us. Since building these wheels is slow, there are
164 multiple mypyc wheels jobs (hence the term "matrix") that build for a specific platform
165 (as noted in the job name in parentheses).
166
167 Like the previous job group, the built wheels are uploaded to PyPI using [twine].
168
169 #### Update stable branch
170
171 So this job doesn't _really_ belong here, but updating the `stable` branch after the
172 other PyPI jobs pass (they must pass for this job to start) makes the most sense. This
173 saves us from remembering to update the branch sometime after cutting the release.
174
175 - _Currently this workflow uses an API token associated with @ambv's PyPI account_
176
177 ### Publish executables
178
179 This workflow builds native executables for multiple platforms using [PyInstaller]. This
180 allows people to download the executable for their platform and run _Black_ without a
181 [Python runtime](https://wiki.python.org/moin/PythonImplementations) installed.
182
183 The created binaries are stored on the associated GitHub Release for download over _IPv4
184 only_ (GitHub still does not have IPv6 access 😢).
185
186 ### docker
187
188 This workflow uses the QEMU powered `buildx` feature of Docker to upload an `arm64` and
189 `amd64`/`x86_64` build of the official _Black_ Docker image™.
190
191 - _Currently this workflow uses an API Token associated with @cooperlees account_
192
193 ```{note}
194 This also runs on each push to `main`.
195 ```
196
197 [black-actions]: https://github.com/psf/black/actions
198 [build]: https://pypa-build.readthedocs.io/
199 [calver]: https://calver.org
200 [cibuildwheel]: https://cibuildwheel.readthedocs.io/
201 [gh-3139]: https://github.com/psf/black/pull/3139
202 [github actions]: https://github.com/features/actions
203 [github release]: https://github.com/psf/black/releases
204 [new-release]: https://github.com/psf/black/releases/new
205 [mypyc]: https://mypyc.readthedocs.io/
206 [mypyc-platform-support]:
207   /faq.html#what-is-compiled-yes-no-all-about-in-the-version-output
208 [pyinstaller]: https://www.pyinstaller.org/
209 [sdist]:
210   https://packaging.python.org/en/latest/glossary/#term-Source-Distribution-or-sdist
211 [twine]: https://github.com/features/actions
212 [wheels]: https://packaging.python.org/en/latest/glossary/#term-Wheel