Revise update-dependency flow to resolve issue #3930 (#3957)

* Update 'test-install' workflow to address requirements/ issues.

Identify and attempt to remedy inconsistencies of the requirements/
files with setup.json.

* Update commit comment for inconsistent requirements/ files.

* Use Python 3.8 consistently for dependency checks.

* Require check-requirements job to succeed to execute 'tests' jobs.

With inconsistent requirements/ files those tests are misleading.

* Provide detailed error message for missing matches of dependencies.

With some refactorization of the utils/dependency_management.py script.

* Allow to turn off file annotation as part of GitHub actions workflow.

To avoid the duplication of the warnings as part of the 'test-install'
workflow.

* Add README.md for requirements/ directory.

To provide some context for the purpose of the contained files.

* Ignore unrelated files for check-requirements command.

* Only create commit comment for expected check-requirements errors.

* Simplify comments in test-install workflow to be more concise.

Co-Authored-By: Leopold Talirz <[email protected]>

* Improve commit and PR comments.

Co-Authored-By: Leopold Talirz <[email protected]>

* Improve wording of requirements/README.md

Co-Authored-By: Leopold Talirz <[email protected]>

* Fix line number in commit warning message referring to setup.json.

* Remove obsolete update-requirements workflow.

Co-authored-by: Leopold Talirz <[email protected]>

.github/workflows/ci.yml

@@ -81,26 +81,23 @@ jobs:
       run: pip install packaging==20.3 click~=7.0 pyyaml~=5.1 toml
 
     - name: Check requirements files
+      id: check_reqs
       run: python ./utils/dependency_management.py check-requirements DEFAULT
 
     - name: Create commit comment
-      if: failure()
+      if: failure() && steps.check_reqs.outputs.error
       uses: peter-evans/commit-comment@v1
       with:
-        token: ${{ secrets.GITHUB_TOKEN }}
         path: setup.json
         body: |
-          It appears that at least one of the environments defined in the requirements files
-          ('requirements/*.txt') is not meeting the dependencies specified in the 'setup.json' file.
-          These files define the environment for continuous integration tests, so it is important that they are updated.
+          ${{ steps.check_reqs.outputs.error }}
 
-          If this commit is part of a pull request, you can automatically update the requirements by
-          commenting with '/update-requirements'.
-
-          Click [here](https://github.com/aiidateam/aiida-core/wiki/AiiDA-Dependency-Management) for more information.
+          Click [here](https://github.com/aiidateam/aiida-core/wiki/AiiDA-Dependency-Management) for more information on dependency management.
 
   tests:
 
+    needs: [check-requirements]
+
     runs-on: ubuntu-latest
     timeout-minutes: 30
 

.github/workflows/test-install.yml

@@ -23,10 +23,10 @@ jobs:
     steps:
     - uses: actions/checkout@v2
 
-    - name: Set up Python 3.7
+    - name: Set up Python 3.8
       uses: actions/setup-python@v1
       with:
-        python-version: 3.7
+        python-version: 3.8
 
     - name: Install dm-script dependencies
       run: pip install packaging==20.3 click~=7.0 pyyaml~=5.1 toml
@@ -155,3 +155,114 @@ jobs:
         AIIDA_TEST_BACKEND: ${{ matrix.backend }}
       run:
         .github/workflows/tests.sh
+
+    - name: Freeze test environment
+      run: pip freeze | sed '1d' | tee requirements-py-${{ matrix.python-version }}.txt
+
+    # Add python-version specific requirements/ file to the requirements.txt artifact.
+    # This artifact can be used in the next step to automatically create a pull request
+    # updating the requirements (in case they are  inconsistent with the setup.json file).
+    - uses: actions/upload-artifact@v1
+      if: matrix.backend == 'django'  # The requirements are identical between backends.
+      with:
+        name: requirements.txt
+        path: requirements-py-${{ matrix.python-version }}.txt
+
+# Check whether the requirements/ files are consistent with the dependency specification in the setup.json file.
+# If the check fails, warn the user via a comment and try to automatically create a pull request to update the files
+# (does not work on pull requests from forks).
+
+  check-requirements:
+
+    needs: tests
+
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Set up Python 3.8
+      uses: actions/setup-python@v1
+      with:
+        python-version: 3.8
+
+    - name: Install dm-script dependencies
+      run: pip install packaging==20.3 click~=7.0 pyyaml~=5.1 toml
+
+    - name: Check consistency of requirements/ files
+      id: check_reqs
+      continue-on-error: true
+      run: python ./utils/dependency_management.py check-requirements DEFAULT --no-github-annotate
+
+#
+# The following steps are only executed if the consistency check failed.
+#
+    - name: Create commit comment
+      if: steps.check_reqs.outcome == 'Failure'  # only run if requirements/ are inconsistent
+      uses: peter-evans/commit-comment@v1
+      with:
+        token: ${{ secrets.GITHUB_TOKEN }}
+        path: setup.json
+        body: |
+          The requirements/ files are inconsistent!
+
+    # Check out the base branch so that we can prepare the pull request.
+    - name: Checkout base branch
+      if: steps.check_reqs.outcome == 'Failure'  # only run if requirements/ are inconsistent
+      uses: actions/checkout@v2
+      with:
+        ref: ${{ github.head_ref }}
+        clean: true
+
+    - name: Download requirements.txt files
+      if: steps.check_reqs.outcome == 'Failure'  # only run if requirements/ are inconsistent
+      uses: actions/download-artifact@v1
+      with:
+        name: requirements.txt
+        path: requirements
+
+    - name: Commit requirements files
+      if: steps.check_reqs.outcome == 'Failure'  # only run if requirements/ are inconsistent
+      run: |
+        git add requirements/*
+
+    - name: Create pull request for updated requirements files
+      if: steps.check_reqs.outcome == 'Failure'  # only run if requirements/ are inconsistent
+      id: create_update_requirements_pr
+      continue-on-error: true
+      uses: peter-evans/create-pull-request@v2
+      with:
+        committer: GitHub <[email protected]>
+        author: ${{ github.actor }} <${{ github.actor }}@users.noreply.github.com>
+        branch: update-requirements
+        commit-message: "Automated update of requirements/ files."
+        title: "Update requirements/ files."
+        body: |
+          Update requirements files to ensure that they are consistent
+          with the dependencies specified in the 'setup.json' file.
+
+          Please note, that this pull request was likely created to
+          resolve the inconsistency for a specific dependency, however
+          other versions that have changed since the last update will
+          be included as part of this commit as well.
+
+          Click [here](https://github.com/aiidateam/aiida-core/wiki/AiiDA-Dependency-Management) for more information.
+
+    - name: Create PR comment on success
+      if: steps.create_update_requirements_pr.outcome == 'Success'
+      uses: peter-evans/create-or-update-comment@v1
+      with:
+        issue-number: ${{ github.event.number }}
+        body: |
+          I automatically created a pull request (#${{ steps.create_update_requirements_pr.outputs.pr_number }}) that adapts the
+          requirements/ files according to the dependencies specified in the 'setup.json' file.
+
+    - name: Create PR comment on failure
+      if: steps.create_update_requirements_pr.outcome == 'Failure'
+      uses: peter-evans/create-or-update-comment@v1
+      with:
+        issue-number: ${{ github.event.number }}
+        body: |
+          Please update the requirements/ files to ensure that they
+          are consistent with the dependencies specified in the 'setup.json' file.

requirements/README.md

@@ -0,0 +1,7 @@
+# README
+
+The `requirements-*.txt` files within this directory define the Python environment used for the *continuous integration tests* of this package. Note: For instructions on how to install the package for regular use, please see the documentation.
+
+The consistency of the requirements defined here with the dependencies defined in the `setup.json` file is checked automatically as part of the continuous integration workflow.
+
+https://github.com/aiidateam/aiida-core/wiki/AiiDA-Dependency-Management