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

Makefile

@@ -1,6 +1,10 @@
 # Do things in edx-platform
-.PHONY: clean extract_translations help pull pull_translations push_translations requirements shell upgrade
-.PHONY: api-docs docs guides swagger
+.PHONY: api-docs-sphinx api-docs base-requirements check-types clean \
+  compile-requirements detect_changed_source_translations dev-requirements \
+  docker_auth docker_build docker_push docker_tag docs extract_translations \
+  guides help lint-imports local-requirements pre-requirements pull \
+  pull_translations push_translations requirements shell swagger \
+  technical-docs test-requirements ubuntu-requirements upgrade-package upgrade
 
 # Careful with mktemp syntax: it has to work on Mac and Ubuntu, which have differences.
 PRIVATE_FILES := $(shell mktemp -u /tmp/private_files.XXXXXX)
@@ -138,6 +142,10 @@ compile-requirements: pre-requirements $(COMMON_CONSTRAINTS_TXT) ## Re-compile *
 upgrade:  ## update the pip requirements files to use the latest releases satisfying our constraints
 	$(MAKE) compile-requirements COMPILE_OPTS="--upgrade"
 
+upgrade-package: ## update just one package to the latest usable release
+	@test -n "$(package)" || { echo "\nUsage: make upgrade_package package=...\n"; exit 1; }
+	$(MAKE) compile-requirements COMPILE_OPTS="--upgrade-package $(package)"
+
 check-types: ## run static type-checking tests
 	mypy
 

requirements/README.rst

@@ -12,21 +12,23 @@ directly in the requirements directory.)
 
 .. _OEP-18: https://github.com/openedx/open-edx-proposals/blob/master/oeps/oep-0018-bp-python-dependencies.rst
 
-Upgrading/downgrading just one dependency
------------------------------------------
+Upgrading just one dependency
+-----------------------------
 
-Want to upgrade just *one* dependency without pulling in other upgrades? Here's how:
+Want to upgrade just *one* dependency without pulling in other upgrades? You can `run the upgrade-one-python-dependency.yml workflow <https://github.com/openedx/edx-platform/actions/workflows/upgrade-one-python-dependency.yml>`_ to have a pull request made against a branch of your choice.
 
-1. Change your dependency to a minimum-version constraint, e.g. ``my-dep>=1.2.3`` (or update the constraint if it already exists)
-2. Run ``make compile-requirements`` to recompute dependencies with this new constraint
+Or, if you need to do it locally, you can use the ``upgrade-package`` make target directly. For example, you could run ``make upgrade-package package=ecommerce``. But the GitHub workflow is likely easier.
 
-If you instead need to surgically *downgrade* a dependency, perhaps in order to revert a change which broke things:
+Downgrading a dependency
+------------------------
 
-1. Add an exact-match or max-version constraint to ``constraints.txt`` with a comment explaining why (and ideally a ticket or issue link)
-2. Lower the minimum-version constraint, if it exists
+If you instead need to surgically *downgrade* a dependency:
 
-    - Not sure if there is one? Try going on to the next step and seeing if it complains!
+1. Add an exact-match or max-version constraint to ``constraints.txt`` with a comment explaining why (and ideally a ticket or issue link). Here's what it might look like::
 
-3. Run ``make compile-requirements``
+     # frobulator 2.x has breaking API changes; see https://github.com/openedx/edx-platform/issue/1234567 for fixing it
+     frobulator<2.0.0
+
+2. Run ``make compile-requirements``
 
 This is considerably safer than trying to manually edit the ``*.txt`` files, which can easily result in incompatible dependency versions.