Release process docs (#2214)

* Setup groundwork for release process docs

I'm using MyST for the index page since I like it more and it's easier
to work with.

* Fill in Release Process for black

* Apply suggestions from code review

Apply Jelle's grammar + typo fixes. I am a terrible only English speaker.

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
* Update release_process.md

Make lint happy via web UI.

* Move to contribution section and fix prettier

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst
index 68dfcd60c28ec19f9ce76c75bd650b9ccac0a835..e7a7f9fb231c28ce1d1fcfbb14692ad50b0d6be3 100644 (file)
--- a/docs/contributing/index.rst
+++ b/docs/contributing/index.rst
@@ -6,6 +6,7 @@ Contributing
 
   the_basics
   gauging_changes
+  release_process
   reference/reference_summary
 
 Welcome! Happy to see you willing to make the project better. Have you read the entire
@@ -31,6 +32,7 @@ This section covers the following topics:
 
 - :doc:`the_basics`
 - :doc:`gauging_changes`
+- :doc:`release_process`
 - :doc:`reference/reference_summary`
 
 For an overview on contributing to the *Black*, please checkout :doc:`the_basics`.

diff --git a/docs/contributing/release_process.md b/docs/contributing/release_process.md
new file mode 100644 (file)
index 0000000..fadef4b
--- /dev/null
+++ b/docs/contributing/release_process.md
@@ -0,0 +1,72 @@
+# Release process
+
+_Black_ has had a lot of work automating its release process. This document sets out to
+explain what everything does and how to release _Black_ using said automation.
+
+## Cutting a Relase
+
+To cut a realease, you must be a _Black_ maintainer with `GitHub Release` creation
+access. Using this access, the release process is:
+
+1. Cut a new PR editing `CHANGES.md` to version the latest changes
+   1. Example PR: https://github.com/psf/black/pull/2192
+   2. Example title: `Update CHANGES.md for XX.X release`
+2. Once the release PR is merged ensure all CI passes
+   1. If not, ensure there is an Issue open for the cause of failing CI (generally we'd
+      want this fixed before cutting a release)
+3. Open `CHANGES.md` and copy the _raw markdown_ of the latest changes to use in the
+   description of the GitHub Release.
+4. Go and [cut a release](https://github.com/psf/black/releases) using the GitHub UI so
+   that all workflows noted below are triggered.
+   1. The release version and tag should be the [CalVer](https://calver.org) version
+      _Black_ used for the current release e.g. `21.6` / `21.5b1`
+   2. _Black_ uses [setuptools scm](https://pypi.org/project/setuptools-scm/) to pull
+      the current version for the package builds and release.
+5. Once the release is cut, you're basically done. It's a good practice to go and watch
+   to make sure all the [GitHub Actions](https://github.com/psf/black/actions) pass,
+   although you should receive an email to your registered GitHub email address should
+   one fail.
+   1. You should see all the release workflows and lint/unittests workflows running on
+      the new tag in the Actions UI
+
+If anything fails, please go read the respective action's log output and configuration
+file to reverse engineer your way to a fix/soluton.
+
+## Release workflows
+
+All _Blacks_'s automation workflows use GitHub Actions. All workflows are therefore
+configured using `.yml` files in the `.github/workflows` directory of the _Black_
+repository.
+
+Below are descriptions of our release workflows.
+
+### Docker
+
+This workflow uses the QEMU powered `buildx` feature of docker to upload a `arm64` and
+`amd64`/`x86_64` build of the official _Black_ docker image™.
+
+- Currently this workflow uses an API Token associated with @cooperlees account
+
+### pypi_upload
+
+This workflow builds a Python
+[sdist](https://docs.python.org/3/distutils/sourcedist.html) and
+[wheel](https://pythonwheels.com) using the latest
+[setuptools](https://pypi.org/project/setuptools/) and
+[wheel](https://pypi.org/project/wheel/) modules.
+
+It will then use [twine](https://pypi.org/project/twine/) to upload both release formats
+to PyPI for general downloading of the _Black_ Python package. This is where
+[pip](https://pypi.org/project/pip/) looks by default.
+
+- Currently this workflow uses an API token associated with @ambv's PyPI account
+
+### Upload self-contained binaries
+
+This workflow builds self-contained binaries for multiple platforms. This allows people
+to download the executable for their platform and run _Black_ without a
+[Python Runtime](https://wiki.python.org/moin/PythonImplementations) installed.
+
+The created binaries are attached/stored on the associated
+[GitHub Release](https://github.com/psf/black/releases) for download over _IPv4 only_
+(GitHub still does not have IPv6 access 😢).