Draft: Refactor GitHub Actions workflows (#1432)

* Refactor GitHub Actions workflows

Changes include:
- Only run on PR creation/change or merge to master branch (stop running on pushes to random branches)
- Combine lint and format checks into one Quality workflow which is based on running pre-commit so it includes additional formatters
- Rename build workflow to tests and change how coverage data gets uploaded to codecov
- Rename mypy workflow to typecheck and also make sure to run it for every version of Python as type support varies

Author: tleonhardt

.github/workflows/doc.yml

@@ -0,0 +1,31 @@
+# For documentation on GitHub Actions Workflows, see:
+# https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions
+name: Docs
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+  push:
+    branches: [master]
+
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  check-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Needed for setuptools_scm to work correctly
+
+      - name: Install uv and set the python version
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.13"
+      - name: Install the project
+        run: uv sync --group docs
+      - name: Check if the MkDocs documentation can be built
+        run: uv run mkdocs build -s

.github/workflows/docs.yml

@@ -0,0 +1,33 @@
+# For documentation on GitHub Actions Workflows, see:
+# https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions
+name: Quality
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+  push:
+    branches: [master]
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Needed for setuptools_scm to work correctly
+
+      - uses: actions/cache@v4
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit-${{ hashFiles('.pre-commit-config.yaml') }}
+      - name: Install uv and set the python version
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.13"
+      - name: Install the project
+        run: uv sync --group quality
+      - name: Run pre-commit
+        run: uv run pre-commit run -a --show-diff-on-failure

.github/workflows/format.yml

@@ -1,22 +1,28 @@
 # For documentation on GitHub Actions Workflows, see:
 # https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions
-name: "build"
-
-on: [push, pull_request]
+name: Tests
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+  push:
+    branches: [master]
 
 jobs:
-  build:
+  tests:
     strategy:
-      fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
         python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14-dev"]
+      fail-fast: false
+
     runs-on: ${{ matrix.os }}
+    defaults:
+      run:
+        shell: bash
     steps:
-      - uses: actions/checkout@v4 # https://github.com/actions/checkout
+      - name: Check out
+        uses: actions/checkout@v4
         with:
-          # Only a single commit is fetched by default, for the ref/SHA that triggered the workflow.
-          # Set fetch-depth: 0 to fetch all history for all branches and tags.
           fetch-depth: 0 # Needed for setuptools_scm to work correctly
       - name: Install uv
         uses: astral-sh/setup-uv@v6
@@ -26,7 +32,6 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
           allow-prereleases: true
-
       - name: Install the project
         run: uv sync --all-extras --dev
 
@@ -35,3 +40,7 @@ jobs:
 
       - name: Run isolated tests
         run: uv run inv pytest --junit --no-pty --isolated
+
+      - name: Upload coverage reports to Codecov with GitHub Action on Python 3.13 for each OS
+        uses: codecov/codecov-action@v3
+        if: ${{ matrix.python-version == '3.13' }}

.github/workflows/lint.yml

@@ -0,0 +1,35 @@
+# For documentation on GitHub Actions Workflows, see:
+# https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions
+name: TypeCheck
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+  push:
+    branches: [master]
+
+permissions:
+  contents: read
+
+jobs:
+  type-check:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+      fail-fast: false
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Check out
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Needed for setuptools_scm to work correctly
+
+      - name: Install uv and set the python version
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Check typing
+        run: uv run mypy .

.github/workflows/mypy.yml

@@ -65,6 +65,7 @@ docs = [
     "setuptools_scm>=8",
 ]
 plugins = ["cmd2-ext-test"]
+quality = ["pre-commit>=2.20.0"]
 test = [
     "codecov>=2",
     "coverage>=7",