add internal release notes

Author: davidhewitt

.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)

Releasing.md

@@ -0,0 +1,56 @@
+# Releasing
+
+This is notes for the current process of releasing a new PyO3 version. Replace `<version>` 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: <version>`. Push to `release-<BRANCH_VER>` branch on the main PyO3 repository, where `<BRANCH_VER>` 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<version>` (note preceding `v`) and target should be the `release-<BRANCH_VER>` 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<prev-version> release-<BRANCH_VER>` 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.

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},
         )