]> 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:

Update description for GitHub Action `options:` argument (GH-2858)
[etc/vim.git] / 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 style -->
51
52 ### _Blackd_
53
54 <!-- Changes to blackd -->
55
56 ### Configuration
57
58 <!-- Changes to how Black can be configured -->
59
60 ### Documentation
61
62 <!-- Major changes to documentation and policies. Small docs changes
63      don't need a changelog entry. -->
64
65 ### Integrations
66
67 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->
68
69 ### Output
70
71 <!-- Changes to Black's terminal output and error messages -->
72
73 ### Packaging
74
75 <!-- Changes to how Black is packaged, such as dependency requirements -->
76
77 ### Parser
78
79 <!-- Changes to the parser or to version autodetection -->
80
81 ### Performance
82
83 <!-- Changes that improve Black's performance. -->
84
85 ```
86
87 ## Release workflows
88
89 All _Blacks_'s automation workflows use GitHub Actions. All workflows are therefore
90 configured using `.yml` files in the `.github/workflows` directory of the _Black_
91 repository.
92
93 Below are descriptions of our release workflows.
94
95 ### Docker
96
97 This workflow uses the QEMU powered `buildx` feature of docker to upload a `arm64` and
98 `amd64`/`x86_64` build of the official _Black_ docker image™.
99
100 - Currently this workflow uses an API Token associated with @cooperlees account
101
102 ### pypi_upload
103
104 This workflow builds a Python
105 [sdist](https://docs.python.org/3/distutils/sourcedist.html) and
106 [wheel](https://pythonwheels.com) using the latest
107 [setuptools](https://pypi.org/project/setuptools/) and
108 [wheel](https://pypi.org/project/wheel/) modules.
109
110 It will then use [twine](https://pypi.org/project/twine/) to upload both release formats
111 to PyPI for general downloading of the _Black_ Python package. This is where
112 [pip](https://pypi.org/project/pip/) looks by default.
113
114 - Currently this workflow uses an API token associated with @ambv's PyPI account
115
116 ### Upload self-contained binaries
117
118 This workflow builds self-contained binaries for multiple platforms. This allows people
119 to download the executable for their platform and run _Black_ without a
120 [Python Runtime](https://wiki.python.org/moin/PythonImplementations) installed.
121
122 The created binaries are attached/stored on the associated
123 [GitHub Release](https://github.com/psf/black/releases) for download over _IPv4 only_
124 (GitHub still does not have IPv6 access 😢).
125
126 ## Moving the `stable` tag
127
128 _Black_ provides a stable tag for people who want to move along as _Black_ developers
129 deem the newest version reliable. Here the _Black_ developers will move once the release
130 has been problem free for at least ~24 hours from release. Given the large _Black_
131 userbase we hear about bad bugs quickly. We do strive to continually improve our CI too.
132
133 ### Tag moving process
134
135 #### stable
136
137 From a rebased `main` checkout:
138
139 1. `git tag -f stable VERSION_TAG`
140    1. e.g. `git tag -f stable 21.5b1`
141 1. `git push --tags -f`