Merge pull request #233 from ImperialCollegeLondon/release/1.0.0

Release version 1.0.0

.github/ISSUE_TEMPLATE/bug_report.md

@@ -4,7 +4,6 @@ about: Create a report to help us improve
 title: ''
 labels: 'bug'
 assignees: ''
-
 ---
 
 **Describe the bug**

.github/ISSUE_TEMPLATE/feature_request.md

@@ -4,7 +4,6 @@ about: Suggest an idea for this project
 title: ''
 labels: ''
 assignees: ''
-
 ---
 
 **Is your feature request related to a problem? Please describe.**

.github/pull_request_template.md

@@ -0,0 +1,24 @@
+
+# Description
+
+Please include a summary of the change and which issue is fixed. Please also include
+relevant motivation and context. List any dependencies that are required for this
+change.
+
+Fixes # (issue)
+
+## Type of change
+
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Optimization (back-end change that speeds up the code)
+- [ ] Bug fix (non-breaking change which fixes an issue)
+
+## Key checklist
+
+- [ ] Make sure you've run the `pre-commit` checks: `$ pre-commit run -a`
+- [ ] All tests pass: `$ poetry run pytest`
+
+## Further checks
+
+- [ ] Code is commented, particularly in hard-to-understand areas
+- [ ] Tests added that prove fix is effective or that feature works

.github/workflows/pyrealm_ci.yaml

@@ -1,15 +1,20 @@
 name: Test and build
 
-on: [push, pull_request, release]
+# When does this run - new, reopened or updated PRs, pushes to main or develop and when
+# the workflow is called by another workflow, such as the publishing actions.
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+  workflow_call:
 
 jobs:
   qa:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
         with:
-          python-version: "3.9"
+          python-version: "3.11"
       - uses: pre-commit/[email protected]
 
   test:
@@ -19,12 +24,14 @@ jobs:
       fail-fast: false
       matrix:
         os: [ ubuntu-latest, macos-latest, windows-latest ]
-        python-version: [ "3.9" , "3.10"]
+        python-version: ["3.10", "3.11", "3.12"]
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
+      with:
+        ref: ${{ github.head_ref }}
 
-    - uses: actions/setup-python@v4
+    - uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
 
@@ -37,20 +44,24 @@ jobs:
       run: poetry install
 
     - name: Run tests
-      run: poetry run pytest
+      run: poetry run pytest -m "not profiling" --cov-report xml
 
-    - name: Run codecov
-      if: success() && (matrix.os == 'ubuntu-latest' && matrix.python-version == 3.9)
+    - name: Upload coverage reports to Codecov
+      id: codecov
+      if: success() && (matrix.os == 'ubuntu-latest' && matrix.python-version == 3.10)
       uses: codecov/codecov-action@v3
+      env:
+        CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
 
   docs_build:
     needs: qa
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
         with:
-          python-version: "3.9"
+          python-version: "3.11"
 
       - name: Install Poetry
         uses: abatilo/[email protected]
@@ -59,11 +70,16 @@ jobs:
 
       - name: Install dependencies
         run: poetry install
-
-      - name: Set ipython kernel
-        run: poetry run python -m ipykernel install --user --name=pyrealm_python3
 
       - name: Build docs using sphinx
         run: |
           cd docs
-          poetry run sphinx-build -W --keep-going source build
+          poetry run sphinx-build -W --keep-going source build
+
+      - name: Archive built docs for error checking on failure
+        if: failure()
+        uses: actions/upload-artifact@v3
+        with:
+          name: built-docs
+          path: docs/build
+          retention-days: 2

.github/workflows/pyrealm_profiling_after_push.yaml

@@ -0,0 +1,79 @@
+name: Profiling after push
+
+# This runs when code is pushed to main or develop
+on:
+  push:
+    branches: [main, develop]
+
+jobs:
+  test:
+    uses: ./.github/workflows/pyrealm_ci.yaml
+    secrets: inherit
+
+  profiling:
+    needs: test
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        ref: ${{ github.head_ref }}
+
+    - uses: actions/setup-python@v5
+      with:
+        python-version: "3.10"
+
+    - name: Install Poetry
+      uses: abatilo/[email protected]
+      with:
+        poetry-version: 1.8.2
+
+    - name: Install dependencies and add env vars
+      run: |
+        poetry install
+        sudo apt-get install graphviz
+        calculatedSha=$(git rev-parse --short ${{ github.sha }})
+        echo "COMMIT_SHORT_SHA=$calculatedSha" >> $GITHUB_ENV
+
+    - name: Run the profiling test suite, using time to get peak memory usage
+      id: profiling
+      run: poetry run /usr/bin/time -v pytest -m "profiling" --profile-svg
+
+    # This step only runs if the profiling succeeds
+    - name: Benchmark performance
+      id: benchmarking
+      if: ${{steps.profiling.outcome == 'success'}}
+      run: poetry run python profiling/run_benchmarking.py prof/combined.prof profiling/profiling-database.csv profiling/benchmark-fails.csv ${{ env.COMMIT_SHORT_SHA }} --update-on-pass --plot-path profiling/performance-plot.png
+
+    # This step copies over the updated call graph
+    - name: Copy call graph
+      id: update-call-graph
+      if: always() && steps.benchmarking.outcome != 'skipped'
+      run: cp prof/combined.svg profiling/call-graph.svg
+
+    # Creates a PR to update the profiling stats if the benchmark passes or fails and
+    # skips if the profiling step fails.
+    - name: Create pull request
+      id: cpr
+      if: always() && steps.benchmarking.outcome != 'skipped'
+      uses: peter-evans/create-pull-request@v6
+      with:
+        commit-message: Updating profiling stats for ${{ env.COMMIT_SHORT_SHA }}
+        title: Updating profiling stats for ${{ env.COMMIT_SHORT_SHA }}
+        add-paths: profiling/*
+        body: |
+          Automatic update of profiling stats.
+
+          - Profiling update for merge of ${{ env.COMMIT_SHORT_SHA }} into ${{ github.head_ref }}
+          - Updated call graph, benchmark plot and profiling stats database.
+          - Auto-generated by `pyrealm_profiling.yaml` workflow 
+
+          ${{ steps.benchmarking.outcome != 'passed' && 'Benchmarking passed' || 'Benchmarking **failed**: review failures.' }}
+
+    - name: Check outputs
+      if: ${{ steps.cpr.outputs.pull-request-number }}
+      run: |
+        echo "Pull Request Number - ${{ steps.cpr.outputs.pull-request-number }}"
+        echo "Pull Request URL - ${{ steps.cpr.outputs.pull-request-url }}"

.github/workflows/pyrealm_profiling_on_approve.yaml

@@ -0,0 +1,64 @@
+name: Profiling on approve
+
+# This runs when a pull request is submitted
+on:
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  test:
+    if: github.event.review.state == 'APPROVED'
+    uses: ./.github/workflows/pyrealm_ci.yaml
+    secrets: inherit
+
+  profiling:
+    needs: test
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        ref: ${{ github.ref }}
+
+    - uses: actions/setup-python@v5
+      with:
+        python-version: "3.10"
+
+    - name: Install Poetry
+      uses: abatilo/[email protected]
+      with:
+        poetry-version: 1.8.2
+
+    - name: Install dependencies and add env vars
+      run: |
+        poetry install
+        sudo apt-get install graphviz
+        calculatedSha=$(git rev-parse --short ${{ github.sha }})
+        echo "COMMIT_SHORT_SHA=$calculatedSha" >> $GITHUB_ENV
+
+    - name: Run the profiling test suite, using time to get peak memory usage
+      id: profiling
+      run: poetry run /usr/bin/time -v pytest -m "profiling" --profile-svg
+
+    # This step only runs if the profiling succeeds
+    - name: Benchmark performance
+      id: benchmarking
+      if: ${{steps.profiling.outcome == 'success'}}
+      run: poetry run python profiling/run_benchmarking.py prof/combined.prof profiling/profiling-database.csv profiling/benchmark-fails.csv ${{ env.COMMIT_SHORT_SHA }} --update-on-pass --plot-path profiling/performance-plot.png
+
+    # This step copies over the updated call graph
+    - name: Copy call graph
+      id: update-call-graph
+      if: always() && steps.benchmarking.outcome != 'skipped'
+      run: cp prof/combined.svg profiling/call-graph.svg
+
+    # This runs if the benchmark passes or fails and skips if the profiling step fails.
+    # The commit message includes [skip actions] to avoid triggering a new round
+    - uses: stefanzweifel/git-auto-commit-action@v5
+      if: always() && steps.benchmarking.outcome != 'skipped'
+      with:
+        commit_message: Auto-generated profiling results [skip actions]
+        file_pattern: 'profiling/*'
+        branch: ${{ github.event.pull_request.head.ref }}