Zum Inhalt

Contributing

Entwicklungsumgebung einrichten

Repository klonen

git clone https://git.bg-kooperation.de/novareto/form_download_helper.git
cd form_download_helper

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

make hooks
# manuell mit uv:
uv run --extra dev pre-commit install

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

tests/
└── test_download.py      # Download-Funktionalität und Hilfsfunktionen

Neue Features entwickeln

1. Issue erstellen

Erstellen Sie ein Issue für neue Features oder Bugfixes:

  1. Gehen Sie zu GitLab Issues
  2. Beschreiben Sie das Problem/Feature detailliert
  3. 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

# Änderungen machen
# Tests schreiben
# Code fixen + alles prüfen
make fix
make check

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

  1. Push Branch: git push origin feature/neue-funktionalität
  2. Erstellen Sie eine Merge Request in GitLab
  3. Beschreiben Sie Änderungen detailliert
  4. Verlinken Sie relevante Issues
  5. 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

  1. Änderungen per Merge Request auf main mergen (CI-prüft Lint/Tests etc.).
  2. Der release-Job analysiert die semantischen Commits seit dem letzten Release und leitet die nächste Version ab:
  3. fix: → Patch (0.1.1)
  4. feat: → Minor (0.2.0)
  5. BREAKING CHANGE: / feat!: → Major (1.0.0)
  6. semantic-release übernimmt alles Weitere:
    • setzt den Tag vX.Y.Z und erstellt eine GitLab-Release mit Release-Notes
  7. Der Tag triggert build-package und deploy-package (Upload in die GitLab PyPI-Registry), build-docs und pages verö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:

git commit -m "feat(download): support pydantic schema endpoint"

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 → version nicht 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

import logging

logging.basicConfig(level=logging.DEBUG)

Häufige Probleme

Import Fehler:

# Stellen Sie sicher, dass das Paket im Development-Modus installiert ist
pip install -e .

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