From f1ce47bd2b0150d2b7c78beaafd3b60c469345d0 Mon Sep 17 00:00:00 2001 From: Cooper Lees Date: Mon, 10 May 2021 07:58:36 -0700 Subject: [PATCH] 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 * 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 --- docs/contributing/index.rst | 2 + docs/contributing/release_process.md | 72 ++++++++++++++++++++++++++++ 2 files changed, 74 insertions(+) create mode 100644 docs/contributing/release_process.md diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst index 68dfcd6..e7a7f9f 100644 --- 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 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 😢). -- 2.39.5