From 88be8ac7e70a105aabaccc70dde23c9967fa2951 Mon Sep 17 00:00:00 2001 From: David Hewitt <1939362+davidhewitt@users.noreply.github.com> Date: Thu, 29 Sep 2022 08:30:11 +0100 Subject: [PATCH] add internal release notes --- .github/workflows/changelog.yml | 6 ++-- Releasing.md | 56 +++++++++++++++++++++++++++++++++ noxfile.py | 11 +++++-- 3 files changed, 68 insertions(+), 5 deletions(-) create mode 100644 Releasing.md diff --git a/.github/workflows/changelog.yml b/.github/workflows/changelog.yml index ae3eaf3f..4f8be1bc 100644 --- a/.github/workflows/changelog.yml +++ b/.github/workflows/changelog.yml @@ -8,7 +8,7 @@ jobs: check: name: Check changelog entry runs-on: ubuntu-latest - if: ${{ !contains(github.event.pull_request.labels.*.name, 'CI-skip-changelog') }} + if: ${{ !contains(github.event.pull_request.labels.*.name, 'CI-skip-changelog') && !startsWith(github.event.pull_request.title, 'release:') }} steps: - uses: actions/checkout@v3 - uses: actions/github-script@v6 @@ -17,7 +17,7 @@ jobs: script: | const fs = require('node:fs') const path = require('node:path') - + let found = false const changeTypes = ['packaging', 'added', 'changed', 'removed', 'fixed'] for (changeType of changeTypes) { @@ -27,7 +27,7 @@ jobs: break } } - + if (!found) { const errorMsg = '📝 Changelog entry not found, please add one (or more) to `newsfragments` directory. For more information see https://github.com/PyO3/pyo3/blob/main/Contributing.md#documenting-changes' core.error(errorMsg) diff --git a/Releasing.md b/Releasing.md new file mode 100644 index 00000000..c7b28e8d --- /dev/null +++ b/Releasing.md @@ -0,0 +1,56 @@ +# Releasing + +This is notes for the current process of releasing a new PyO3 version. Replace `` in all instructions below with the new version. + +## 1. Prepare the release commit + +Follow the process below to update all required pieces to bump the version. All these changes are done in a single commit because it makes it clear to git readers what happened to bump the version. It also makes it easy to cherry-pick the version bump onto the `main` branch when tidying up branch history at the end of the release process. + +1. Replace all instances of the PyO3 current version with the new version to be released. Places to check: + - `Cargo.toml` for all PyO3 crates in the repository. + - PyO3 version embedded into documentation like the README. + - `pre-script.rhai` templates for the examples. + - `[towncrier]` section in `pyproject.toml`. + + Places where you need to be a bit careful: + - Add _new_ lines to the netlify `_redirects` file rather than replacing the existing ones. + - Make sure not to modify the CHANGELOG during this step! + +2. Run `towncrier build` to generate the CHANGELOG. The version used by `towncrier` should automatically be correct because of the update to `pyproject.toml` in step 1. + +3. Manually edit the CHANGELOG for final notes. Steps to do: + - Adjust wording of any release lines to make them clearer for users / fix typos. + - Add a new link at the bottom for the new version, and update the `Unreleased` link. + +4. Create the commit containing all the above changes, with a message of `release: `. Push to `release-` branch on the main PyO3 repository, where `` depends on whether this is a major or minor release: + - for O.X.0 minor releases, just use `0.X`, e.g. `release-0.17`. This will become the maintenance branch after release. + - for 0.X.Y patch releases, use the full `0.X.Y`, e.g. `release-0.17.1`. This will be deleted after merge. + +## 2. Create the release PR and draft release notes + +Open a PR for the branch, and confirm that it passes CI. For `0.X.0` minor releases, the PR should be merging into `main`, for `0.X.Y` patch releases, the PR should be merging the `release-0.X` maintenance branch. + +On https://github.com/PyO3/pyo3/releases, click "Draft a new release". The tag will be a new tag of `v` (note preceding `v`) and target should be the `release-` branch you just pushed. + +Write release notes which match the style of previous releases. You can get the list of contributors by running `nox -s contributors -- v release-` to get contributors from the previous version tag through to the branch tip you just pushed. (This uses the GitHub API, so you'll need to push the branch first.) + +Save as a draft and wait for now. + +## 3. Leave for a cooling off period + +Wait a couple of days in case anyone wants to hold up the release to add bugfixes etc. + +## 4. Put live + +To put live: +- 1. run `nox -s publish` to put live on crates.io +- 2. publish the release on Github +- 3. merge the release PR + +## 5. Tidy the main branch + +If the release PR targeted a branch other than main, you will need to cherry-pick the version bumps, CHANGELOG modifications and removal of towncrier `newsfragments` and open another PR to land these on main. + +## 6. Delete the release branch (patch releases only) + +For 0.X.Y patch releases, the release branch is no longer needed, so it should be deleted. diff --git a/noxfile.py b/noxfile.py index 49c11c9f..7fd157ac 100644 --- a/noxfile.py +++ b/noxfile.py @@ -110,17 +110,24 @@ def publish(session: nox.Session) -> None: def contributors(session: nox.Session) -> None: import requests - if len(session.posargs) != 1: + if len(session.posargs) < 1: raise Exception("base commit positional argument missing") base = session.posargs[0] page = 1 + head = "HEAD" + if len(session.posargs) == 2: + head = session.posargs[1] + + if len(session.posargs) > 2: + raise Exception("too many arguments") + authors = set() while True: resp = requests.get( - f"https://api.github.com/repos/PyO3/pyo3/compare/{base}...HEAD", + f"https://api.github.com/repos/PyO3/pyo3/compare/{base}...{head}", params={"page": page, "per_page": 100}, )