build: Add upgrade-package Make target and workflow (#32131)

This adds a Make target that should simplify the common task of
upgrading a single dependency. Sometimes people manually edit the pin
files, which we would like to avoid; hopefully this will make it
easier for them to do the right thing.

The GitHub workflow should also make it easier for people on Mac to
recompile requirements in a Linux environment, reducing the number of
times spurious dependency changes show up in the pin files (due to
OS-dependent requirements.)

Also, separate upgrade/downgrade instructions and simplify the latter.
(Min constraints are rare and we usually move beyond them quickly.)

.github/workflows/upgrade-one-python-dependency.yml

@@ -0,0 +1,75 @@
+name: Upgrade one Python dependency
+
+on:
+  workflow_dispatch:
+     inputs:
+       branch:
+         description: 'Target branch to create requirements PR against'
+         required: true
+         default: 'master'
+         type: string
+       package:
+         description: 'Name of package to upgrade'
+         required: true
+         type: string
+
+defaults:
+  run:
+    shell: bash # making this explicit opts into -e -o pipefail
+
+jobs:
+  upgrade-one-python-dependency-workflow:
+    runs-on: ubuntu-20.04
+
+    steps:
+      - name: Check out target branch
+        uses: actions/checkout@v3
+        with:
+          ref: "${{ inputs.branch }}"
+
+      - name: Set up Python environment
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.8"
+
+      - name: Run make upgrade-package
+        env:
+          PACKAGE: "${{ inputs.package }}"
+        run: |
+          make upgrade-package package="$PACKAGE"
+
+      - name: PR preflight
+        run: |
+          if git diff --exit-code; then
+              # Fail early (and avoid quiet failure of create-pull-request action)
+              echo "Error: No changes, so not creating PR." | tee -a "$GITHUB_STEP_SUMMARY"
+              exit 1
+          else
+              : # do nothing; exit code 1 means there are changes (good!)
+          fi
+
+      - name: Make a PR
+        id: make-pr
+        uses: peter-evans/create-pull-request@v5
+        with:
+          branch: "${{ github.triggering_actor }}/upgrade-${{ inputs.package }}"
+          branch-suffix: short-commit-hash
+          add-paths: requirements
+          commit-message: |
+            feat: Upgrade Python dependency ${{ inputs.package }}
+
+            Commit generated by workflow `${{ github.workflow_ref }}`
+          title: "feat: Upgrade Python dependency ${{ inputs.package }}"
+          body: "PR generated by workflow `${{ github.workflow_ref }}` on behalf of @${{ github.triggering_actor }}."
+          assignees: "${{ github.triggering_actor }}"
+
+      - name: Job summary
+        env:
+          PR_URL: "${{ steps.make-pr.outputs.pull-request-url }}"
+        run: |
+          if [[ -z "$PR_URL" ]]; then
+              echo "PR not created; see log for more information" | tee -a "$GITHUB_STEP_SUMMARY"
+              exit 1
+          else
+              echo "PR created or updated: $PR_URL" | tee -a "$GITHUB_STEP_SUMMARY"
+          fi