Entwicklung

In diesem Kapitel werden Sie in die Entwicklung von MultiGeiger eingeführt.

MultiGeiger ist in C geschrieben und benutzt Arduino-ESP32.

Beiträge

…sind willkommen!

Einige Hinweise für Beitragende:

  • diskutieren Sie über Änderungen auf dem Github-Issue-Tracker
  • machen Sie Ihre PRs gegen den master-Branch
  • machen Sie saubere Changesets:
    • konzentrieren Sie sich auf ein Thema, ändern Sie nichts anderes.
    • machen Sie keine Stiländerungen gemischt mit funktionalen Änderungen.
    • lassen Sie den automatischen Code-Formatierer laufen, bevor Sie committen
    • versuchen Sie, Refactoring gemischt mit funktionalen Änderungen zu vermeiden.
    • wenn Sie nach dem Commit/Push etwas korrigieren müssen:
      • wenn es laufende Überprüfungen gibt: machen Sie einen Fixup-Commit, den Sie später mit dem schlechten Commit zusammenführen können.
      • Wenn es keine laufenden Überprüfungen gibt oder Sie den schlechten Commit noch nicht gepusht haben: Bearbeiten Sie den Commit, um Ihre Korrektur einzuschließen oder führen Sie ihn mit dem Fixup-Commit vor dem Pushen zusammen.
    • schreiben Sie einen schönen, klaren, tippfehlerfreien Commit-Kommentar
    • wenn Sie ein Problem behoben haben, verweisen Sie darauf in Ihrem Commit-Kommentar
  • Machen Sie einen Pull-Request auf Github und überprüfen Sie auf der PR-Seite, was das CI-System über den Code in Ihrem PR sagt
  • Warten Sie auf die Überprüfung durch andere Entwickler

Eine Entwicklungsumgebung aufbauen

TODO

Automatischer Code-Formatierer

Wir verwenden astyle für automatische Code-Formatierung / Formatierungsprüfungen.

Führen Sie es wie folgt aus:

astyle --options=.astylerc 'multigeiger/\*'

Dokumentation

Erstellen der Dokumentation mit Sphinx

Die Dokumentation wird in Englisch geschrieben und dann von dieser Quelle aus in andere Sprachen übersetzt (anfangs Deutsch).

Die Dokumentation (im reStructuredText-Format, .rst) befindet sich in docs/source/, index.rst ist der Startpunkt dort.

Um die Dokumentation zu erstellen, müssen Sie Sphinx installiert haben und dies ausführen:

cd docs/
make html

Rufen Sie dann einen Webbrowser für docs/build/html/index.html auf.

Die Website wird von ReadTheDocs automatisch über GitHub-Web-Hooks auf dem Haupt-Repository aktualisiert.

Nach Änderungen an den (englischen) Master-Docs müssen die Übersetzungs-Masterdateien (*.pot) aktualisiert werden (Hinzufügen/Entfernen/Aktualisieren von Strings darin):

cd docs/build/gettext
sphinx-build -b gettext ../../source .

Dann müssen diese Änderungen nach transifex gepusht werden, damit die Übersetzer bequem im Web übersetzen können:

Die Übersetzung ist auf [transifex](https://www.transifex.com/thomaswaldmann/multigeiger/) organisiert, Du brauchst dort ein Konto oder musst zumindest Dich dort einloggen und einen „Team beitreten“-Antrag absetzen. Dann die fehlenden Teile übersetzen und den Entwicklern Bescheid sagen (z. B. über den Issue Tracker).

tx push --source

Später, nachdem die Übersetzer ihren Teil erledigt haben, müssen die aktualisierten Übersetzungen von transifex gepulled werden:

tx pull --all --force

Jetzt haben wir Änderungen in unserem Git-Workdir und müssen sie committen:

git add locales/
git commit -m "updated translations"
git push

Dies wird einen Build der Dokumentation und ihrer Übersetzung(en) auf readthedocs.io auslösen.

Geräte flashen / Binärdateien erzeugen

Arduino IDE:

  • Führen Sie ein Git Checkout der gewünschten Version durch, z.B. git checkout V1.13.0

  • verwenden Sie die Standard userdefines.h (verfügbar als userdefines-example.h)

  • IDE-Einstellungen:

    • Gerät: Heltec WiFi Stick (diesen immer verwenden, auch wenn Sie ein WiFi Kit 32 haben)
    • Flash-Größe: 4MB (32Mb)
    • Partitionsschema: minimal SPIFFS (große APPS mit OTA) - das passt auf 4MB-Geräte.
  • Arduino IDE -> Sketch -> Hochladen

    Dies ist zum Testen, ob der kompilierte Code nach dem USB-Flashen auf Ihr Gerät tatsächlich funktioniert.

  • Arduino IDE -> Sketch -> Kompilierte Binärdatei exportieren

    Dies erzeugt eine .bin-Datei für die OTA-Aktualisierung. Testen Sie, ob die OTA-Aktualisierung mit dieser Datei funktioniert.

Erstellen eines neuen Releases

Checkliste:

  • Sicherstellen, dass alle Probleme für diesen Meilenstein geschlossen oder zum nächsten Meilenstein verschoben worden sind
  • Prüfen Sie, ob es noch ausstehende Korrekturen für schwerwiegende Probleme gibt
  • prüfen, ob ein CA-Zertifikat (siehe ca_certs.h) bald abläuft und ob wir bereits deren nächstes gültiges Zertifikat hinzufügen können.
  • alle einfach zu lösenden Probleme im Issue Tracker finden und beheben
  • Release-Meilenstein auf Github schließen
  • Aktualisieren von docs/source/changes.rst, basierend auf git log $PREVIOUS_RELEASE..
  • bump2version --new-version 1.23.0 release - dies wird:
    • die Versionen überall aktualisieren
    • einen Git-Tag automatisch erstellen
    • einen Git-Commit automatisch erstellen
  • Überprüfen Sie das automatisch erzeugte Changeset
  • einen Github-Release für dieses Tag erstellen:
    • Erstellen Sie ein Binary (siehe oben) und hängen Sie es an den Github-Release an
    • Fügen Sie einen Link zum relevanten changes.rst-Abschnitt zum Github-Release hinzu
  • bump2version --no-tag --current-version 1.23.0 minor - dies wird:
    • die Versionen überall aktualisieren (jetzt auf: 1.24.0-dev)
    • leider nicht ganz korrekt die changes.rst aktualisieren, so dass manuelle Korrekturen danach notwendig sind
    • nach der Korrektur: git commit –amend