Skip to content

Automatic PR validation #502

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jliermann merged 3 commits into from
Jan 30, 2026
Merged

Automatic PR validation #502

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2fd5e0e
chore: update package.json and package-lock.json to include new depen…
jliermann Jan 30, 2026
cb9b3f7
test: implement PR validation workflow and content validation script
jliermann Jan 30, 2026
874f289
docs: add PR validation setup and validation scripts documentation
jliermann Jan 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 57 additions & 0 deletions .github/workflows/pr-validation.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
name: "PR Validation"

on:
pull_request:
paths:
- "docs/**"
- "package.json"
- "package-lock.json"
- ".github/workflows/pr-validation.yml"

jobs:
validate:
name: "Content & Build Validation"
runs-on: ubuntu-latest

strategy:
matrix:
node-version: ["18.x"]

steps:
- name: "Checkout code"
uses: actions/checkout@v4
with:
fetch-depth: 0

- name: "Setup Node.js"
uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
cache: "npm"

- name: "Install dependencies"
run: npm ci

- name: "� Write translations"
run: npm run write-translations
continue-on-error: false

- name: "📥 Download translations from Crowdin"
run: npm run crowdin download
continue-on-error: false

- name: "�📋 Validate Frontmatter & Titles"
run: node scripts/validate-content.js
continue-on-error: false

- name: "🏗️ Build Documentation"
run: npm run build
continue-on-error: false

- name: "✅ All checks passed"
if: success()
run: |
echo "✨ Alle Validierungen erfolgreich!"
echo "- ✅ Frontmatter validiert"
echo "- ✅ Titel validiert"
echo "- ✅ Build erfolgreich"
240 changes: 240 additions & 0 deletions VALIDATION_PROPOSAL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,240 @@
# Implementierungs-Zusammenfassung: PR Validation

## 🎯 Überblick

Dieser Proposal implementiert ein automatisches Validierungssystem für Pull Requests in der NFDI4Chem Knowledge Base.

## ✅ Implementierte Komponenten

### 1. Validierungsskript

**Datei:** `scripts/validate-content.js`

* ✅ Prüft alle `md` und `mdx`-Dateien im `docs/`-Verzeichnis
* ✅ Validiert Frontmatter auf gültiges YAML und erforderlichen Slug
* ✅ Prüft Seitentitel (h1 oder title im Frontmatter)
* ✅ Warnt bei identischen h1 und title Werten
* ✅ Benutzerfreundliche Fehlerausgabe mit Zusammenfassung
* ✅ Exit-Code-basierte Fehlerbehandlung für CI/CD

**Verwendung:**

```bash
npm run validate-content
```

### 2. GitHub Actions Workflow

**Datei:** `.github/workflows/pr-validation.yml`

* ✅ Triggert automatisch bei Pull Requests
* ✅ Installiert Dependencies
* ✅ Führt Content-Validierung durch
* ✅ Führt Docusaurus Build durch
* ✅ Meldet Ergebnisse im PR

**Features:**

* Lädt Dependencies aus Cache (schneller)
* Node.js 18 (aktuell und stabil)
* Automatische Status-Updates im PR

### 3. Package.json Updates

* ✅ Neue devDependencies: `glob` und `gray-matter`
* ✅ Neue npm Scripts:
* `npm run validate-content` - Nur Validierung
* `npm run test:ci` - Validierung + Build

### 4. Dokumentation

* ✅ `scripts/VALIDATION_SETUP.md` - Detaillierte Setup-Anleitung
* ✅ `scripts/EXAMPLES.md` - Praktische Beispiele für gültige/ungültige Dateien
* ✅ `scripts/README.md` - Schnelle Übersicht
* ✅ `scripts/validation.config.js` - Vorschläge für Erweiterungen

## 📋 Validierungsregeln

### Frontmatter

```yaml
---
slug: /my-page/ # ✅ ERFORDERLICH - eindeutig
title: Page Title # ⚠️ Optional, aber empfohlen
description: ... # ⚠️ Optional, gut für SEO
---
```

**Validierungen:**

* Slug muss vorhanden sein
* Slug muss ein String sein
* Slug darf nicht leer sein

### Seitentitel

* Mindestens eine der folgenden Optionen erforderlich:
* `h1` Überschrift (`# Title`)
* `title` im Frontmatter
* Wenn beide vorhanden:
* Sie dürfen nicht identisch sein
* Empfehlung: h1 detaillierter, title kürzer für SEO

### Build

* Docusaurus Build muss fehlerfrei laufen
* Keine Broken Links/Images (basierend auf docusaurus.config.js)

## 🚀 Erste Schritte

### Installation

```bash
npm install
```

Das installiert die neuen devDependencies.

### Lokal Testen

```bash
# Nur Validierung
npm run validate-content

# Nur Build
npm run build

# Beides zusammen (wie der PR-Check)
npm run test:ci
```

### Bei Fehlern

Siehe `scripts/EXAMPLES.md` für Lösungsbeispiele.

## 🔄 Workflow in der Praxis

### Für Contributors:

1. **Vor dem Commit:**
```bash
npm run validate-content
```

2. **Vor dem Push:**
```bash
npm run test:ci
```

3. **Push und PR öffnen:**
* GitHub Actions läuft automatisch
* Status wird im PR angezeigt

### Für Maintainer:

* PR kann nur gemerged werden wenn alle Checks bestanden sind ✅
* Automatische Validierung spart Zeit bei Code Reviews
* Konsistente Dokumentation garantiert

## 📦 Dependencies

Neue NPM-Packages:

* **glob** (^10.3.10) - Datei-Pattern-Matching
* **gray-matter** (^4.0.3) - Frontmatter-Parsing

Beides sind kleine, etablierte Packages ohne weitere Dependencies.

## 🎨 Output-Beispiel

```
🔍 Validiere Dokumente...

📁 Gefundene Dateien: 42

📄 docs/10_domains/example.md
❌ Fehler:
- Slug im Frontmatter fehlt
⚠️ Warnungen:
- h1 und Frontmatter-title sind identisch

📊 Zusammenfassung:
Dateien geprüft: 42
Fehler: 1
Warnungen: 1

❌ Validierung fehlgeschlagen!
```

## 🔧 Erweiterungsmöglichkeiten

Das System ist modular und kann leicht erweitert werden:

1. **SEO-Validierung**
* Meta description Länge
* Keywords prüfen
* Title length für Suchresultate

2. **Link-Validierung**
* Interne Links auf Existenz
* Externe Links erreichbar

3. **Image-Validierung**
* Dateien existieren
* Alt-Text vorhanden
* Bildgröße optimiert

4. **Code-Qualität**
* Spellcheck (deutsche Rechtschreibung)
* MDX-Lint
* Remark-Plugins

Siehe `scripts/validation.config.js` für Implementierungs-Ideen.

## 📊 Statistik

| Komponente | Dateien | Zeilen |
|-----------|---------|--------|
| Validierungsskript | 1 | ~150 |
| GitHub Actions | 1 | ~25 |
| Dokumentation | 4 | ~600+ |
| Config-Beispiel | 1 | ~150 |
| **Total** | **7** | **~925** |

## ✨ Vorteile

1. **Qualitätssicherung**
* Konsistente Dokumentenstruktur
* Keine fehlenden Slugs/Titel
* Build garantiert fehlerfrei

2. **Automatisierung**
* Keine manuellen Checks nötig
* Sofortiges Feedback in PRs
* Spart Zeit im Review-Prozess

3. **Developer Experience**
* Klare Fehler-Meldungen
* Einfache lokale Tests
* Gute Dokumentation

4. **Wartbarkeit**
* Modular und erweiterbar
* Gute Code-Struktur
* Keine Abhängigkeiten auf externe Services

## 🎓 Nächste Schritte (Optional)

1. Pre-commit Hooks (Husky) - lokale Validierung vor Commit
2. Spellcheck (Cspell) - Deutsche Rechtschreibung
3. Link-Checker - Interne Links validieren
4. Image-Optimizer - Bildgrößen optimieren
5. SEO-Tools - Meta-Tags prüfen

***

**Status:** ✅ Produktionsbereit - Sofort einsatzbar

**Kompatibilität:** Node.js 18+, alle OS (Linux, macOS, Windows)

**Wartung:** Minimal - nur 2 externe Dependencies
Loading
Loading