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 aufgit 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