Skip to content

contribution.adoc

Latest commit

 

History

History
178 lines (119 loc) · 6.67 KB

contribution.adoc

File metadata and controls

178 lines (119 loc) · 6.67 KB
Note

Da PySignalduino noch in aktiver Entwicklung ist, können sich Code-Strukturen und APIs schnell ändern. Bitte synchronisieren Sie Ihren Fork regelmäßig mit dem upstream-Repository.

Beiträge zum Projekt sind willkommen!

Workflow

  1. Fork & Clone: Projekt forken und lokal klonen.

  2. Branch: Feature-Branch erstellen (git checkout -b feature/mein-feature).

  3. Entwicklung: Änderungen implementieren.

  4. Tests: Sicherstellen, dass alle Tests bestehen (pytest).

  5. Pull Request: PR auf GitHub öffnen.

Entwicklungsumgebung

Abhängigkeiten installieren

Das Projekt verwendet poetry für die Abhängigkeitsverwaltung. Installieren Sie die Entwicklungsabhängigkeiten mit:

link:../examples/bash/install_dev_deps.sh[role=include]

Oder verwenden Sie poetry install (falls Poetry konfiguriert ist).

Die wichtigsten Entwicklungsabhängigkeiten sind:

  • pytest – Testframework

  • pytest-mock – Mocking-Unterstützung

  • pytest-asyncio – Asyncio-Testunterstützung

  • pytest-cov – Code-Coverage

  • aiomqtt – Asynchrone MQTT-Client-Bibliothek (für Tests gemockt)

Code-Stil und Linting

Das Projekt folgt PEP 8. Verwenden Sie black für automatische Formatierung und ruff für Linting.

link:../examples/bash/format_code.sh[role=include]

Es gibt keine strikte CI-Prüfung, aber konsistenter Stil wird erwartet.

Dokumentationsstil

Für alle AsciiDoc-Dateien im docs/ Verzeichnis ist die Regel "Ein Satz pro Zeile" verpflichtend. Dies erleichtert die Überprüfung von Änderungen mittels git diff.

Important

Jeder Satz muss auf einer neuen Zeile beginnen. Ein Satz endet typischerweise mit einem Punkt (.), Ausrufezeichen (!) oder Fragezeichen (?). Achten Sie darauf, dass Codeblöcke und Tabellen nicht betroffen sind.

Tests ausführen

Das Projekt nutzt pytest. Stellen Sie sicher, dass requirements-dev.txt installiert ist.

link:../examples/bash/run_pytest.sh[role=include]

Für spezifische Testmodule:

link:../examples/bash/run_specific_tests.sh[role=include]

Asyncio-Tests

Seit der Migration zu asyncio (Version 0.9.0) sind alle Tests asynchron und verwenden pytest-asyncio. Testfunktionen müssen mit @pytest.mark.asyncio dekoriert sein und async def verwenden.

Beispiel:

link:../../tests/test_controller.py[role=include]

Mocking asynchroner Objekte

Verwenden Sie AsyncMock aus unittest.mock, um asynchrone Methoden zu mocken. Achten Sie darauf, asynchrone Kontextmanager (aenter, aexit) korrekt zu mocken.

link:../../tests/conftest.py[role=include]

In Fixtures (siehe tests/conftest.py) werden Transport- und MQTT-Client-Mocks bereitgestellt.

Test-Coverage

Coverage-Bericht generieren:

link:../examples/bash/coverage_report.sh[role=include]

Der Bericht wird im Verzeichnis htmlcov/ erstellt.

Code-Stil und Best Practices für asyncio

Allgemeine Richtlinien

  • Verwenden Sie async/await für alle E/A-Operationen.

  • Vermeiden Sie blockierende Aufrufe (z.B. time.sleep, synchrones Lesen/Schreiben) in asynchronen Kontexten. Nutzen Sie stattdessen asyncio.sleep.

  • Nutzen Sie asynchrone Iteratoren (async for) und Kontextmanager (async with), wo passend.

Asynchrone Queues

  • Verwenden Sie asyncio.Queue für die Kommunikation zwischen Tasks.

  • Achten Sie auf korrekte Behandlung von Queue.task_done() und await queue.join().

  • Setzen Sie angemessene Timeouts, um Deadlocks zu vermeiden.

Fehlerbehandlung

  • Fangen Sie asyncio.CancelledError in Tasks, um saubere Beendigung zu ermöglichen.

  • Verwenden Sie asyncio.TimeoutError für Timeouts bei asyncio.wait_for.

  • Protokollieren Sie Ausnahmen mit logger.exception in except-Blöcken.

Ressourcenverwaltung

  • Implementieren Sie aenter/aexit für Ressourcen, die geöffnet/geschlossen werden müssen (Transport, MQTT-Client).

  • Stellen Sie sicher, dass aexit auch bei Ausnahmen korrekt aufgeräumt wird.

Performance

  • Vermeiden Sie das Erstellen zu vieler gleichzeitiger Tasks; nutzen Sie asyncio.gather mit angemessener Begrenzung.

  • Verwenden Sie asyncio.create_task für Hintergrundtasks, aber behalten Sie Referenzen, um sie später abbrechen zu können.

Pull-Request Prozess

  1. Vor dem Einreichen: Stellen Sie sicher, dass Ihr Branch auf dem neuesten Stand von main ist und alle Tests bestehen.

  2. Beschreibung: Geben Sie im PR eine klare Beschreibung der Änderungen, des Problems und der Lösung an.

  3. Review: Mindestens ein Maintainer muss den PR reviewen und genehmigen.

  4. Merge: Nach Genehmigung wird der PR gemergt (Squash-Merge bevorzugt).

Checkliste für PRs

  • ❏ Tests hinzugefügt/aktualisiert und alle bestehenden Tests bestehen.

  • ❏ Code folgt PEP 8 (Black/Ruff).

  • ❏ Dokumentation aktualisiert (falls nötig).

  • ❏ Keine neuen Warnungen oder Fehler im Linter.

  • ❏ Changelog aktualisiert (optional, wird vom Maintainer übernommen).

AI‑Agenten Richtlinien

Für AI‑Agenten, die Code oder Systemkonfigurationen ändern, gelten zusätzliche verbindliche Vorgaben. Jede Änderung muss eine vollständige Analyse der Auswirkungen auf die zugehörige Dokumentation und die Testsuite umfassen.

Die detaillierten Richtlinien sind in AGENTS.md dokumentiert. Die wichtigsten Pflichten sind:

  • Dokumentationspflicht: Die Dokumentation muss synchron zu allen vorgenommenen Änderungen aktualisiert werden. Betroffen sind das docs/‑Verzeichnis, Inline‑Kommentare, Docstrings, README.md und andere Markdown‑Dateien.

  • Test‑Pflicht: Bestehende Tests sind zu überprüfen und anzupassen; bei Bedarf sind neue Tests zu erstellen, um eine vollständige Testabdeckung der neuen oder modifizierten Logik zu gewährleisten.

  • Verbindlichkeit: Diese Praxis ist für jede Änderung verbindlich und nicht verhandelbar. Ein Commit, der die Dokumentation oder Tests nicht entsprechend anpasst, ist unzulässig.

Vor dem Commit ist die Checkliste in AGENTS.md (Abschnitt „Mandatory Documentation and Test Maintenance“) abzuarbeiten.

Hinweise für Protokoll-Entwicklung

Falls Sie ein neues Funkprotokoll hinzufügen möchten:

  1. Fügen Sie die Definition in sd_protocols/protocols.json hinzu.

  2. Implementieren Sie die Dekodierungsmethode in der entsprechenden Mixin-Klasse (ManchesterMixin, PostdemodulationMixin, etc.).

  3. Schreiben Sie Tests für das Protokoll in tests/test_manchester_protocols.py oder ähnlich.

  4. Dokumentieren Sie das Protokoll in docs/03_protocol_reference/protocol_details.adoc.

Weitere Details finden Sie in der Architektur-Dokumentation (architecture.adoc).