Contributing
Entwicklungsumgebung einrichten
Repository klonen
Abhängigkeiten installieren
make dev # Komplette Entwicklungsumgebung (Lint-/Test-/Docs-Tools)
# manuell mit uv:
uv sync --extra dev
# Oder mit pip:
pip install -e ".[dev]"
Pre-commit-Hooks installieren
Danach wird vor jedem Commit automatisch make check (Lint, Format, Typ-Check, Tests) ausgeführt — fehlerhafter Code wird nicht committet. Ausnahmefall: git commit --no-verify überspringt den Hook.
Code-Stil
Das gesamte Linting, Formatting und Typ-Checking läuft über das Makefile (ruff für Formatierung und Linting, ty für das statische Typ-Checking). Zu jedem Target steht die manuelle uv-Variante daneben — die Tools kommen aus dem check-Extra (uv run --extra check installiert sie bei Bedarf automatisch):
# Code formatieren + Lint-Auto-Fix (ändert Dateien)
make fix
# manuell: uv run ruff format && uv run ruff check --fix
# Formatierung prüfen (ohne Änderungen)
make format-check
# manuell: uv run ruff format --check
# Linting
make lint
# manuell: uv run ruff check
# Statisches Typ-Checking
make typecheck
# manuell: uv run ty check
Tests
Tests ausführen
# Alle Tests (mit Coverage)
make test
# manuell: uv run check pytest --cov=form_download_helper --cov-report=xml --cov-report=term
# Alles auf einmal prüfen (lint + format-check + typecheck + test, wie in der CI)
make check
# Nur spezifische Tests
uv run pytest tests/test_download.py
Test-Struktur
Neue Features entwickeln
1. Issue erstellen
Erstellen Sie ein Issue für neue Features oder Bugfixes:
- Gehen Sie zu GitLab Issues
- Beschreiben Sie das Problem/Feature detailliert
- Fügen Sie Labels hinzu (bug, enhancement, etc.)
2. Branch erstellen
# Feature Branch
git checkout -b feature/neue-funktionalität
# Bugfix Branch
git checkout -b bugfix/fehler-beschreibung
3. Entwicklung
4. Commit Guidelines
Verwenden Sie aussagekräftige Commit-Messages:
# Format: type(scope): description
git commit -m "feat(download): add support for multiple versions"
git commit -m "fix(auth): handle authentication errors gracefully"
git commit -m "docs(readme): update installation instructions"
Commit Types:
- feat: Neue Features → erhöht die Minor-Version (released)
- fix: Bugfixes → erhöht die Patch-Version (released)
- docs: Dokumentation
- style: Code-Stil (kein funktioneller Unterschied)
- refactor: Code-Refactoring
- test: Tests hinzufügen/ändern
- chore: Build/Tooling Änderungen
Ein BREAKING CHANGE: im Commit-Body (oder feat!:/fix!:) erhöht zusätzlich die Major-Version. Nur diese drei Signaturen lösen ein Release aus — Details im Release-Prozess.
5. Merge Request
- Push Branch:
git push origin feature/neue-funktionalität - Erstellen Sie eine Merge Request in GitLab
- Beschreiben Sie Änderungen detailliert
- Verlinken Sie relevante Issues
- Fügen Sie Reviewer hinzu
Dokumentation
MkDocs entwickeln
# Dokumentation lokal starten (Live-Reload)
make docs-serve
# manuell mit uv:
uv run mkdocs serve
# Dokumentation bauen (strict, wie in der CI)
make docs
# manuell mit uv:
uv run mkdocs build --strict
Docstrings
Verwenden Sie Google-Style Docstrings:
def download(
path: Path,
username: str,
password: str,
version: str,
uri: str,
package: str | None = None,
):
"""Download form data and generate files.
Args:
path: Target directory for downloads
username: Username for authentication
password: Password for authentication
version: Form version number
uri: Form URI to download from
package: Python package name (auto-detected if omitted)
Returns:
None
Raises:
requests.RequestException: If download fails
IOError: If file operations fail
Example:
>>> download(Path("/tmp"), "user", "pass", 2, "https://example.com")
"""
Release-Prozess
Releases laufen vollautomatisch über semantic-release — Versionen und Tags werden nicht manuell für Releases gesetzt.
Ablauf
- Änderungen per Merge Request auf
mainmergen (CI-prüft Lint/Tests etc.). - Der
release-Job analysiert die semantischen Commits seit dem letzten Release und leitet die nächste Version ab: fix:→ Patch (0.1.1)feat:→ Minor (0.2.0)BREAKING CHANGE:/feat!:→ Major (1.0.0)- semantic-release übernimmt alles Weitere:
- setzt den Tag
vX.Y.Zund erstellt eine GitLab-Release mit Release-Notes
- setzt den Tag
- Der Tag triggert
build-packageunddeploy-package(Upload in die GitLab PyPI-Registry),build-docsundpagesveröffentlichen die Dokumentation.
Die Paketversion wird im Tag-Build aus dem Tag abgeleitet und nur in der CI gesetzt; pyproject.toml wird dabei nicht geändert oder committet.
Ausschließlich semantische Commit-Messages schreiben (siehe Commit Guidelines) — sie sind der einzige Input für Versionsnummer und Release-Notes:
Beim Squash-Merge eines MR muss die Squash-Commit-Message semantisch sein — sie ist der Input für das Release.
Grenzen des Automatismus
- Commits ohne semantisches Schema (
FIX,changes, …) erzeugen kein Release. pyproject.toml→versionnicht für einen Release hochzählen; veröffentlichte Paketversionen kommen aus den Tags.- Kein
vX.Y.Z-Tag manuell setzen oder löschen — semantic-release setzt die Tags.
Debugging
Logging aktivieren
Häufige Probleme
Import Fehler:
Test Fehler:
# Cache leeren
pytest --cache-clear
# Einzelne Tests debuggen
pytest -v -s tests/test_download.py::test_specific_function
Authentifizierung testen:
# Mit curl testen
curl -u username:password "https://formulare.uv-kooperation.de/ozg/rul/ozg-90/@@meta-schema?version=2"
Code Review
Checkliste für Reviewer
- [ ] Code folgt Stil-Guidelines
- [ ] Tests sind vorhanden und funktionieren
- [ ] Dokumentation ist aktualisiert
- [ ] Keine sensiblen Daten im Code
- [ ] Performance-Impact berücksichtigt
- [ ] Backward-Kompatibilität gewährleistet
Feedback geben
- Seien Sie konstruktiv und höflich
- Erklären Sie das "Warum" bei Änderungsvorschlägen
- Schlagen Sie Alternativen vor
- Anerkennen Sie gute Lösungen
Community
Fragen stellen
- Nutzen Sie GitLab Issues für Bugs und Features
- Diskussionen über GitLab Discussions
- E-Mail an Maintainer bei dringenden Problemen
Code of Conduct
- Respektvoller Umgang miteinander
- Konstruktive Kritik
- Inklusives Verhalten
- Fokus auf technische Verbesserungen