Umfassendes RAUC Dokumentations-Update

Enrico Jörns | | RAUC, Documentation

Wie in vielen Projekten, ist auch bei RAUC an vielen Stellen nach massiver Entwicklung meist nicht mehr ausreichend Zeit geblieben, die Änderungen, neuen Features und grundlegenden Konzepte angemessen aufbereitet in der Dokumentation unterzubringen und zu erklären.

Statistik
  Vorher Nachher
Zeilen 2135 3522
Wörter 9275 16805
Zeichen 66991 119992

https://rauc.readthedocs.io

Damit fallen nicht nur nützliche und sinnvolle Features unter den Tisch, sondern es häufen sich auch Nachfragen und Missverständnisse, die mit einer guten Dokumentation von vornherein hätten ausgeräumt werden können.

Daher hat Pengutronix eine gesamte Woche lang den virtuellen Zettel und Stift in die Hand genommen, um die Dokumentation von RAUC an vielen Stellen grundlegend umzukrempeln und zu erweitern.

Das Ergebnis kann sich durchaus sehen lassen, wenn man allein auf die quantitative Auswirkung schaut. Nach Anzahl Zeichen hat sich der Umfang der Dokumentation um knapp 80% vergrößert.

Die Struktur und der Inhalt der einleitenden Kapitel, welche grundlegende Konzepte und Ideen hinter RAUC für den Benutzer in einer Übersicht darstellen sollen, wurden komplett überarbeitet und um viele Aspekte ergänzt. Darüber hinaus wurden einige Themenkomplexe mit anschaulichen Grafiken untermalt.

Mit dem neu geschaffenen Kapitel Scenarios wird auf einige der am häufigsten verwendeten Redundanz-Setups eingegangen und an Konfigurations-Beispielen gezeigt, wie sie in RAUC realisiert werden können.

Technisch deutlich detaillierter wurden auch die wichtigen Kapitel zur Integration von Barebox und U-Boot ausgeführt.

Komplett neu hinzugekommen sind auch eine ganze Reihe weiterführender Themen wie Umgang mit Sicherheit, Erzeugung und Behandlung von Zertifikaten, Applikationsdaten-Behandlung und -Migration, Bootloader-Updates oder Software Deployment.

Auch wenn es robuste Frameworks wie RAUC gibt, zur Entwicklung eines individuell passenden und soliden Update-Konzeptes gehören viel Know-How und Sorgfalt bei der Zusammenstellung und Konfiguration des Gesamtsystems. Von der Auswahl des Bootloaders über das Aufsetzen und die Behandlung des Watchdogs bis hin zur Detektierung eines erfolgreich gebooteten Userspace müssen diverse Komponenten eng ineinandergreifen.

Mit der neu eingeführten Design Checklist haben wir daher einen grundlegenden Laufzettel erarbeitet, der (ohne Anspruch auf Vollständigkeit) vielen generellen Fallstricken beim Design und bei der Realisierung von Update-Konzepten zuvorkommen soll.