feat: add Tailwind CSS pipeline, tag-aware cloning & overhaul CI/CD (#352)

Frontend

* introduce Tailwind CSS (package.json, tailwind.config.js, input CSS)
* build site.css on-the-fly (removed tracked artefact; added .gitignore)
* new favicon/icon assets & template cleanup
* split JS into modular files

Docker

* replace single-stage image with 3-stage build
  • css-builder (Node 20 alpine) → compiles Tailwind
  • python-builder installs project with PEP 621 metadata
  • runtime image copies site-packages + compiled CSS, runs as uid 1000

CI/CD

* ci.yml: cache by pyproject.toml, install with `pip -e .[dev]`
* new frontend job builds/archives CSS after tests
* publish.yml: build CSS first, then wheel/sdist; trusted OIDC upload
* tidy scorecard workflow

Core library

* clone.py, parser & utils now resolve tags in addition to branches/commits
* fallback branch/tag discovery when `git ls-remote` fails
* compat\_func.py back-ports Path.readlink / str.removesuffix for Py 3.8

Tooling & docs

* add `[dev]` extra, drop requirements-dev.txt & its pre-commit fixer
* refreshed CONTRIBUTING.md with Node/Tailwind instructions
* updated tests for new tag logic

Author: filipchristiansen

.github/dependabot.yml

@@ -1,12 +1,27 @@
 version: 2
 updates:
+  # ─── Python (pip) ─────────────────────────────
   - package-ecosystem: "pip"
     directory: "/"
-    schedule:
-      interval: "daily"
-      time: "06:00"
-      timezone: "UTC"
-    open-pull-requests-limit: 5
-    labels:
-      - "dependencies"
-      - "pip"
+    schedule: { interval: "weekly" }
+    labels: [ "dependencies", "pip" ]
+    groups: # Group patches & minors from dev-only tools
+      dev-py:
+        dependency-type: "development"
+        update-types: ["minor", "patch"]
+
+  # ─── Node (npm) ───────────────────────────────
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule: { interval: "weekly" }
+    labels: [ "dependencies", "npm" ]
+    cooldown:  # wait before opening PRs
+      semver-major-days: 30
+      semver-minor-days: 7
+      semver-patch-days: 3
+
+  # ─── GitHub Actions ───────────────────────────
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule: { interval: "weekly" }
+    labels: [ "dependencies", "gh-actions" ]

.github/workflows/ci.yml

@@ -25,26 +25,50 @@ jobs:
       uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
+    - name: Locate pip cache
+      id: pip-cache
+      shell: bash
+      run: echo "dir=$(python -m pip cache dir)" >> "$GITHUB_OUTPUT"
 
     - name: Cache pip
       uses: actions/cache@v4
       with:
-        path: ~/.cache/pip
-        key: ${{ runner.os }}-pip-${{ hashFiles('**/*requirements*.txt') }}
-        restore-keys: |
-          ${{ runner.os }}-pip-
-
+        path: ${{ steps.pip-cache.outputs.dir }}
+        key: ${{ runner.os }}-pip-${{ hashFiles('pyproject.toml') }}
+        restore-keys: ${{ runner.os }}-pip-
     - name: Install dependencies
       run: |
-        pip install --upgrade pip
-        pip install -r requirements-dev.txt
+        python -m pip install --upgrade pip
+        python -m pip install ".[dev]"
 
     - name: Run tests
-      run: |
-        pytest
+      run: pytest
 
     #  Run pre-commit only on Python 3.13 + ubuntu.
     - name: Run pre-commit hooks
+      uses: pre-commit/action@v3.0.1
       if: ${{ matrix.python-version == '3.13' && matrix.os == 'ubuntu-latest' }}
-      run: |
-        pre-commit run --all-files
+
+  frontend:
+    needs: test # Builds Tailwind CSS only if tests pass
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install Node deps
+        run: npm ci
+
+      - name: Build CSS
+        run: npm run build:css  # Creates src/static/css/site.css
+
+      - name: Upload artefact
+        uses: actions/upload-artifact@v4
+        with:
+          name: static-css
+          path: src/static/css/site.css

.github/workflows/publish.yml

@@ -1,39 +1,88 @@
-name: "Publish to PyPI"
+name: Publish to PyPI
 
 on:
   release:
-    types: [created]
-  workflow_dispatch:
+    types: [created] # Run when you click “Publish release”
+  workflow_dispatch: # ... or run it manually from the Actions tab
 
 permissions:
   contents: read
 
+# ── Build the Tailwind CSS bundle ───────────────────────────────
 jobs:
+  frontend-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: package-lock.json
+
+      - name: Install deps + build Tailwind
+        run: |
+          npm ci
+          npm run build:css
+
+      - name: Upload built CSS
+        uses: actions/upload-artifact@v4
+        with:
+          name: frontend-assets
+          path: src/static/css/site.css
+          if-no-files-found: error
+
+# ── Build wheel/sdist (needs CSS) and upload “dist/” ────────────
   release-build:
+    needs: frontend-build
     runs-on: ubuntu-latest
+
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+
+      # Grab site.css produced above
+      - uses: actions/download-artifact@v4
+        with:
+          name: frontend-assets
+          path: src/static/css/
+
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v5
         with:
           python-version: "3.13"
-      - name: Build package
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install build backend
         run: |
-          pip install build
+          python -m pip install --upgrade pip
+          python -m pip install build twine
           python -m build
-      - uses: actions/upload-artifact@v4
+          twine check dist/*
+      - name: Upload dist artefact
+        uses: actions/upload-artifact@v4
         with:
           name: dist
           path: dist/
 
+# ── Publish to PyPI (only if “dist/” succeeded) ─────────────────
   pypi-publish:
-    needs: [release-build]
+    needs: release-build
     runs-on: ubuntu-latest
-    environment: pypi
+    environment: pypi # Creates the “pypi” environment in repo-settings
+
     permissions:
-      id-token: write
+      id-token: write # OIDC token for trusted publishing
+
     steps:
       - uses: actions/download-artifact@v4
         with:
           name: dist
           path: dist/
+
       - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          verbose: true

.github/workflows/scorecard.yml

@@ -1,52 +1,39 @@
 name: OSSF Scorecard
 on:
-  # For Branch-Protection check. Only the default branch is supported. See
-  # https://github.com/ossf/scorecard/blob/main/docs/checks.md#branch-protection
   branch_protection_rule:
-  # To guarantee Maintained check is occasionally updated. See
-  # https://github.com/ossf/scorecard/blob/main/docs/checks.md#maintained
   schedule:
-    - cron: '33 11 * * 2'
+    - cron: '33 11 * * 2'  # Every Tuesday at 11:33 AM UTC
   push:
-    branches: [ "main" ]
+    branches: [ main ]
 
-# Declare default permissions as read only.
-permissions: read-all
+permissions: read-all  # Default for the whole workflow
+
+concurrency:            # (optional) avoid overlapping runs
+  group: scorecard-${{ github.ref }}
+  cancel-in-progress: true
 
 jobs:
   analysis:
     name: Scorecard analysis
     runs-on: ubuntu-latest
     permissions:
-      # Needed to upload the results to code-scanning dashboard.
-      security-events: write
-      # Needed to publish results and get a badge (see publish_results below).
-      id-token: write
+      security-events: write # upload SARIF to code-scanning
+      id-token: write # publish results for the badge
 
     steps:
-      - name: "Checkout code"
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+      - name: Checkout
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
         with:
           persist-credentials: false
 
-      - name: "Run analysis"
-        uses: ossf/scorecard-action@0864cf19026789058feabb7e87baa5f140aac736 # v2.3.1
+      - name: Run Scorecard
+        uses: ossf/scorecard-action@0864cf19026789058feabb7e87baa5f140aac736
         with:
           results_file: results.sarif
           results_format: sarif
+          publish_results: true  # enables the public badge
 
-          # Public repositories:
-          #   - Publish results to OpenSSF REST API for easy access by consumers
-          #   - Allows the repository to include the Scorecard badge.
-          #   - See https://github.com/ossf/scorecard-action#publishing-results.
-          publish_results: true
-
-      # Upload the results as artifacts (optional). Commenting out will disable uploads of run results in SARIF
-      # format to the repository Actions tab.
-
-      # Upload the results to GitHub's code scanning dashboard (optional).
-      # Commenting out will disable upload of results to your repo's Code Scanning dashboard
-      - name: "Upload to code-scanning"
+      - name: Upload to code-scanning
         uses: github/codeql-action/upload-sarif@v3
         with:
           sarif_file: results.sarif

.gitignore

@@ -170,6 +170,9 @@ cython_debug/
 # JavaScript tooling
 node_modules/
 
+# CSS
+src/static/css/site.css
+
 # Project specific
 history.txt
 cleanup.py