Workflow improvements

.github/workflows/build.yaml

@@ -27,7 +27,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
 
       - name: Set up environment for CI
         run: |

.github/workflows/deploy.yml

@@ -13,7 +13,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
 
       - name: Assume AWS IAM Role
         uses: aws-actions/configure-aws-credentials@ec61189d14ec14c8efccab744f656cffd0e33f37

.github/workflows/pre-commit.yml

@@ -0,0 +1,24 @@
+name: pre-commit
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
+        with:
+          python-version: "3.12"
+
+      - name: Run pre-commit hooks
+        run: |
+          python3 -m pip install pre-commit
+          make pre-commit

.github/workflows/test.yml

@@ -12,12 +12,12 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
 
       - name: Set up Python
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
         with:
-          python-version: "3.11"
+          python-version: "3.12"
 
       - name: Validate analysis project schema
         uses: ./.github/actions/validate-analysis-projects
@@ -42,43 +42,34 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
 
       - name: Set up Python
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
         with:
-          python-version: "3.11"
+          python-version: "3.12"
 
       - name: Install project and unit test dependencies
         run: |
-          python -m pip install --upgrade pip
-          pip install -e ".[test]"
+          python3 -m pip install uv
+          make sync-deps-exact
 
-      - name: Run pytest with coverage
+      - name: Run unit tests and measure code coverage
         env:
           PYTEST_DISABLE_PLUGIN_AUTOLOAD: "1"
         run: |
-          python -m pytest \
-                    -m "not e2e" \
-                    --ignore=tests/frontend-smoke/ \
-                    --code-highlight=yes \
-                    --color=yes \
-                    --verbosity=3 \
-                    -p pytest_cov \
-                    --cov=vertex \
-                    --cov-report=term-missing \
-                    --cov-report=xml
+          make test MARKER="unit" TESTS_PATH=tests/unit
 
       - name: Upload coverage.xml artifact
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
         with:
           name: coverage-xml
           path: coverage.xml
           if-no-files-found: error
 
       - name: Upload coverage report to Codecov (best effort)
         continue-on-error: true
-        uses: codecov/codecov-action@57e3a136b779b570ffcdbf80b3bdc90e7fab3de2
+        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f
         with:
           files: ./coverage.xml
           token: ${{ secrets.CODECOV_TOKEN }}
@@ -91,32 +82,28 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
 
       - name: Set up Python
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
         with:
-          python-version: "3.11"
+          python-version: "3.12"
 
       - name: Install frontend smoke test dependencies
         run: |
-          python -m pip install --upgrade pip
-          pip install -e ".[frontend-smoke-tests]"
+          python -m pip install uv
+          make sync-deps-exact
 
       - name: Run frontend smoke tests
         env:
           PLAYWRIGHT_ARTIFACTS_DIR: test-results/playwright
           PYTEST_DISABLE_PLUGIN_AUTOLOAD: "1"
         run: |
-          python -m pytest \
-                    --code-highlight=yes \
-                    --color=yes \
-                    --verbosity=3 \
-                    tests/frontend-smoke/test_playwright_smoke.py
+          make test MARKER="e2e" TESTS_PATH=tests/frontend-smoke
 
       - name: Upload Playwright artifacts on failure
         if: failure()
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
         with:
           name: playwright-artifacts
           path: test-results/playwright

.github/workflows/validate-project-outputs.yml

@@ -32,10 +32,10 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
 
       - name: Set up Python
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
         with:
           python-version: "3.11"
 

.readthedocs.yaml

@@ -38,7 +38,7 @@ sphinx:
 
 python:
   install:
-    - method: pip
-      path: .
-      extra_requirements:
+    - method: uv
+      command: sync
+      groups:
         - docs

Dockerfile

@@ -1,4 +1,4 @@
-FROM python:3.11-slim
+FROM python:3.12-slim
 
 # Set the working directory
 WORKDIR /app

Makefile

@@ -0,0 +1,121 @@
+SHELL := /bin/bash
+
+REPO := https://github.com/ISARICResearch/VERTEX
+
+PACKAGE_NAME := vertex
+BRANCH := $(shell git rev-parse --abbrev-ref HEAD)
+HEAD := $(shell git rev-parse --short=8 HEAD)
+PACKAGE_VERSION := $(shell grep __version__ vertex/__init__.py | cut -d '=' -f 2 | xargs)
+
+PROJECT_ROOT := $(PWD)
+
+TESTS_ROOT := $(PROJECT_ROOT)/tests
+
+DOCS_ROOT := $(PROJECT_ROOT)/docs
+DOCS_BUILD := $(DOCS_ROOT)/_build
+DOCS_BUILD_HTML := $(DOCS_ROOT)/_build/html
+
+
+# --- Git ---
+#
+# Git staging
+git-stage:
+	@echo "$(PACKAGE_NAME)[$(BRANCH)@$(HEAD)]: Staging new, modified, deleted and/or renamed files in Git"
+	git status -uno | grep modified | tr -s ' ' | cut -d ' ' -f 2 | xargs git add && \
+	git status -uno | grep deleted | tr -s ' ' | cut -d ' ' -f 2 | xargs git add -A && \
+	git status -uno
+
+# --- Housekeeping ---
+.PHONY: clean
+clean:
+	@echo "$(PACKAGE_NAME)[$(BRANCH)@$(HEAD)]: Deleting all temporary files"
+	rm -fr dist/* docs/_build/* .pytest_cache *.pyc *__pycache__* ./dist/* ./build/* *.egg-info*
+	python3 -m pip uninstall -y isaric-vertex
+
+# --- Version commands ---
+#
+# Just display the version
+version-extract:
+	@echo "$(PACKAGE_VERSION)"
+
+# --- Member inspection of Python files ---
+#
+# Parameterised command to lexicographically list all callables (functions,
+# classes) in path-specified Python modules including:
+#
+# functions:
+#
+#     list-members MEMBER_REGEX="def" FILE_PATH="/path/to/py/file"
+#
+# classes:
+#
+#     list-members MEMBER_REGEX="class" FILE_PATH="/path/to/py/file"
+#
+# functions or classes (inclusive):
+#
+#     list-members MEMBER_REGEX="def\|class" FILE_PATH="/path/to/py/file"
+#
+# where the '|' represents an OR operator for grep that needs to be escaped with the backslash '\'.
+list-callables:
+	@echo "$(PACKAGE_NAME)[$(BRANCH)@$(HEAD)]: Lexicographical listing of all callable members ($(MEMBER_REGEX)) of a Python file"
+	grep "$(MEMBER_REGEX)" $(FILE_PATH) | sort | cut -d ' ' -f 2 | cut -d '(' -f 1
+
+# --- Dependency management ---
+sync-deps-exact:
+	@echo "$(PACKAGE_NAME)[$(BRANCH)@$(HEAD)]: Syncing all package + development dependencies with lockfile, removing unrelated dependencies"
+	rm -f uv.lock && \
+	uv sync --verbose --all-groups --no-editable --no-install-project --no-cache --refresh --no-managed-python
+
+sync-deps-inexact:
+	@echo "$(PACKAGE_NAME)[$(BRANCH)@$(HEAD)]: Syncing all package + development dependencies with lockfile, preserving unrelated dependencies"
+	rm -f uv.lock && \
+	uv sync --verbose --all-groups --no-editable --no-install-project --no-cache --refresh --inexact --no-managed-python
+
+# --- Package artifacts ---
+#
+# Only source distributions are required, no wheel.
+.PHONY: sdist
+sdist: clean
+	@echo "$(PACKAGE_NAME)[$(BRANCH)@$(HEAD)]: Building a source distribution of VERTEX"
+	uv build --verbose --sdist && ls -al dist/*.tar.gz
+
+.PHONE: uninstall
+uninstall: clean
+	@echo "$(PACKAGE_NAME)[$(BRANCH)@$(HEAD)]: Uninstalling any existing installed VERTEX distribution"
+
+# --- Documentation ---
+.PHONY: clean
+docs: clean
+	@echo "$(PACKAGE_NAME)[$(BRANCH)@$(HEAD)]: Building Sphinx docs (using the Sphinx Makefile in ./docs/)"
+	make -C docs html
+
+# --- Pre-commit ---
+.PHONY: clean
+pre-commit: clean
+	@echo "$(PACKAGE_NAME)[$(BRANCH)@$(HEAD)]: Running pre-commit hooks"
+	pre-commit run --all-files
+
+# --- Tests ---
+#
+# Unit tests - use the `MARKER` variable to indicate markers, e.g.
+# "critical or high", or "medium or low". Note that in the `test` target
+# command below, the `MARKER` variable must be quoted to prevent expansion
+# in case of spaces in the marker.
+.PHONY: test
+test: clean
+	@echo "$(PACKAGE_NAME)[$(BRANCH)@$(HEAD)]: Running unit tests + measuring coverage"
+	PYTHONPATH=src uv run --verbose --active -m pytest \
+	                               -p pytest_cov \
+	                               -q -m "$(MARKER)" \
+	                               --cache-clear \
+	                               --capture=no \
+	                               --code-highlight=yes \
+	                               --color=yes \
+	                               --cov=vertex \
+	                               --cov-report=term-missing:skip-covered \
+	                               --cov-report=xml \
+	                               --cov-report=html \
+	                               -ra \
+	                               --tb=native \
+	                               --verbosity=3 \
+	                               $(TESTS_PATH)

docs/index.rst

@@ -23,12 +23,12 @@ VERTEX processes and visualizes data using the concept of **Reproducible Analyti
 
 See the :doc:`quickstart guide <sources/getting-started>` to start using VERTEX, and the linked pages below for more information on features and code.
 
-VERTEX is licensed under the `Open Source Initiative (OSI) <https://opensource.org>`_-compliant `MIT license <https://opensource.org/license/mit>`_.
+VERTEX is licensed under the `MIT license <https://opensource.org/license/mit>`_.
 
 .. image:: _static/osi-badge-light.svg
    :target: https://opensource.org/license/mit
-   :height: 200px
-   :width:  200px
+   :height: 100px
+   :width:  100px
 
 .. toctree::
    :maxdepth: 1

docs/sources/getting-started.rst

@@ -13,7 +13,7 @@ VERTEX is essentially an app, and there is a `public version <https://vertex.isa
 Requirements
 ~~~~~~~~~~~~
 
-The main VERTEX requirements are Python ``3.11+`` and the
+The main VERTEX requirements are Python ``3.12+`` (although ``3.11`` should also be fine generally) and the
 specific dependencies listed in the ``[project]`` section of the `project TOML <https://github.com/ISARICResearch/VERTEX/blob/main/pyproject.toml>`_.
 
 If you're running VERTEX locally :doc:`in Docker <app>` then these dependencies (and their sub-dependencies) will be pre-installed inside the container, so no direct user installation is required.