Add a GitHub workflow to prepare a release pull request (#6972)

This automates the first half of the current release process. The second
half will be implemented by another workflow.

The reason why it can't all be done in a single workflow is that it's
useful to let developers inspect what'll go into the release before
actually publishing it, and to apply any last-minute fixes, if
necessary. It also allows CI to complete for the release PR.

To support the new workflow, add a `--set` option to `update_version.py`
that sets the version to a custom value.

.github/workflows/prepare-release.yml

@@ -0,0 +1,59 @@
+name: Prepare release
+on:
+  workflow_dispatch:
+    inputs:
+      newVersion:
+        description: "Version number for the new release"
+        required: true
+        default: X.Y.Z
+jobs:
+  main:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Validate version number
+        env:
+          NEW_VERSION: "${{ inputs.newVersion }}"
+        run: |
+          if ! [[ "$NEW_VERSION" =~ [0-9]+\.[0-9]+\.[0-9]+ ]]; then
+            echo "Invalid version number"
+            exit 1
+          fi
+
+      - uses: actions/checkout@v4
+
+      - name: Verify that the release is new
+        run: |
+          if git ls-remote --exit-code origin refs/tags/v${{ inputs.newVersion }} > /dev/null; then
+            echo "Release v${{ inputs.newVersion }} already exists"
+            exit 1
+          fi
+
+      - name: Create release branch
+        run:
+          git checkout -b "release-${{ inputs.newVersion }}"
+
+      - name: Collect changelog
+        run:
+          pipx run scriv collect --version="${{ inputs.newVersion }}"
+
+      - name: Set the new version
+        run:
+          ./dev/update_version.py --set="${{ inputs.newVersion }}"
+
+      - name: Commit release preparation changes
+        run: |
+          git -c user.name='github-actions[bot]' -c user.email='github-actions[bot]@users.noreply.github.com' \
+            commit -a -m "Prepare release v${{ inputs.newVersion }}"
+
+      - name: Push release branch
+        run:
+          git push -u origin "release-${{ inputs.newVersion }}"
+
+      - name: Create release pull request
+        env:
+          GH_TOKEN: "${{ github.token }}"
+        run: |
+          gh pr create \
+            --base=master \
+            --title="Release v${{ inputs.newVersion }}" \
+            --body="$(awk '/^## / { hn += 1; next } hn == 1 && !/^</' CHANGELOG.md)"

dev/update_version.py

@@ -70,6 +70,11 @@ def increment_major(self) -> None:
         self.major += 1
         self._set_default_minor()
 
+    def set(self, v: str) -> None:
+        self.major, self.minor, self.patch = map(int, v.split('.'))
+        self.prerelease = 'final'
+        self.prerelease_number = 0
+
     def _set_default_prerelease_number(self) -> None:
         self.prerelease_number = 0
 
@@ -177,6 +182,9 @@ def main() -> None:
     action_group.add_argument('--verify-current',
         action='store_true', help='Check that all version numbers are consistent')
 
+    action_group.add_argument('--set', metavar='X.Y.Z',
+        help='Set the version to the specified version')
+
     args = parser.parse_args()
 
     version = get_current_version()
@@ -207,6 +215,9 @@ def main() -> None:
     elif args.major:
         version.increment_major()
 
+    elif args.set is not None:
+        version.set(args.set)
+
     else:
         assert False, "Unreachable code"