From b1f8b9339a51cd842b6d80fbb4f7d78e4de22f87 Mon Sep 17 00:00:00 2001 From: Tim McCormack Date: Thu, 27 Apr 2023 09:44:47 -0400 Subject: [PATCH] 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.) --- .../upgrade-one-python-dependency.yml | 75 +++++++++++++++++++ Makefile | 12 ++- requirements/README.rst | 22 +++--- 3 files changed, 97 insertions(+), 12 deletions(-) create mode 100644 .github/workflows/upgrade-one-python-dependency.yml diff --git a/.github/workflows/upgrade-one-python-dependency.yml b/.github/workflows/upgrade-one-python-dependency.yml new file mode 100644 index 0000000000..b8e6a7e14c --- /dev/null +++ b/.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 diff --git a/Makefile b/Makefile index fec1c2caf2..1f835fd976 100644 --- a/Makefile +++ b/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 diff --git a/requirements/README.rst b/requirements/README.rst index 618a3c4c25..1c2b81c131 100644 --- a/requirements/README.rst +++ b/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 `_ 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.