Qualitätssicherungsprozess

[christian-weiss]

Ich finde es super, dass Travis-CI jeden PR prüft.
Sogar, dass bei neuen lokalen Gruppen (Städten) initial geprüft wird, ob die referenzierte API Datei der lokalen Gruppe ok ist, statt nur die directory.json selbst zu prüfen. Auch ok, ist das die API Datei dieser Community geprüft wird, wenn der directory.json Eintrag (Zeile) sich ändert (z.B. um einen Schreibfehler im Stadtnamen zu korrigieren oder eine neue URL einzutragen).

Aktuell prüft Travis-CI jedoch bei einem Delete gleich alle Einträge der directory.json, was wir m.E. nicht tun sollten!

Wenn eine lokale Gruppe Inserts, Updates oder Deletes per PR einreicht, dann sollten nicht durch QA-Probleme in fremden (referenzierten) API Dateien geblockt werden. Ebenso sollte der Merger nicht gezwungen sein den PR-Merge zu verzögern bis alle fremden APIs wieder ok sind, noch sollte er gezwungen sein den fehlgeschlagenen Build zu ignorieren indem er diesen einfach merged.

Das löschen von Zeilen sollte m.E. jedoch nicht dazu führen (wie aktuell) dass alle API Dateien aller Einträge auf Korrektheit überprüft werden. Denn diese sind bewusst dezentral und damit außerhalb des QA-Prozesses für PRs. Das sollte nicht im Rahmen eines "Build Prozesses", sondern mit einem regelmäßigen und unabhängigen Monitoring erfolgen. Zusätzlich darf natürlich jede lokale Gruppe einen QA-Prozess für die eigene API Datei erstellen, die JSON-Schema Dateien von Freifunk zum validieren des JSON liegen ja öffentlich bereit: https://github.com/freifunk/api.freifunk.net/tree/master/specs

Hilfreich wäre es, wenn man ein sample github repo mit einem entsprechendem .travis.yml bereitstellt - dass würde es den lokalen Gruppen leichter machen diesen, eigenen, unabhngigen Prozess aufzusetzen.

Der Prozess zum "Entfernen von Einträgen in der directory.json" sollte m.E. jetzt etwas formaler werden. Er sollte festlegen, wie lange ein falscher URL / eine ungültige API Datei mindestens und maximal toleriert wird.

Ein Mindestwert ist notwendig, damit bei temporären Verbindungsproblemen der Eintrag nicht direkt entfernt wird und damit die lokale Gruppe erst einen neuen PR stellen müsste (welcher ggf. mehrere Tage benötigt, je nach Verfügbarkeit der Personen).

Es ist also wie in der README.md erwähnt eine Rückfrage an die lokale Gruppe notwendig, um sicherzustellen, dass an dem Problem geabeitet wird und in überschaubarer Zeit eine Lösung gefunden wird. Zitat: "Stark veraltete oder ungültige Dateien werden nach Rückfrage wieder entfernt."

Auf der anderen Seite muss sichergestellt sein, dass die directory.json keine große Anzahl an ungültigen Endpunkten auflistet (nicht erreichbare Endpunkte: DNS Einstellungen falsch, URL falsch, Zertifikat abgelaufen/falsch, JSON ungültig, etc.) - es ist also notwendig, dass es einen Maximalwert gibt, der definiert, wie lange man auf eine Lösung wartet, bevor man den Eintrag löscht. Ich persönlich halte 1 Woche für ausreichend lang, da ich erwarte, dass lokale Gruppen aus mehreren Personen bestehen und eine Urlaubsvertretung organisiert wird und Wissenstransfer stattfindet. Zudem kann man im Projekt sicher auch kurzfristig Hilfe bekommen. Wer das nicht sicherstellen kann ist vielleich einfach eine zu kleine lokale Gruppe um sich als Gruppe hier einzutragen (one-man-show).

Da für eine solche Rücksprache Kontaktdaten benötigt werden ist aktuell ein "Rückfrage Prozess" aktuell schwer umzusetzen - die API-Datei kann ja offline sein, wodurch dann keine Kontaktdaten direkt vorliegen. Man muss die Leute kennen oder per Webrecherche / Herumfragen versuchen herauszufinden, wer eine Lösung herbeiführen kann / verantwortlich für die API Datei ist. Das ist zeitaufwändig und bindet unnötig Ressoucen (z.B. des Mergers) die in eine Weiterentwicklung des Projektes sinnvoller investiert wären. Das o.g. Monitoring sollte also die letzte, gültige Version der API Datei cachen oder wir sollten einen API Verantwortlichen in das Schema der directory.json aufnehmen. Von Letzterem rate ich ab, da sowas häufig nicht gepflegt wird (es müsste jedes mal ein PR vorausgehen).

O.g. Monitoring entsteht zur Zeit hier:
http://community-registry.ff-hamm.de/
Dieser Report ist ein Alpha-Preview, wird noch nicht stündlich aktualisiert, und noch nicht alle Werte sind dynamisch ermittelt (Implementierung findet aktuell statt und wird noch detailierter und wird auch Optimierungstips geben).

Jede lokale Gruppe soll dort die Möglichkeit bekommen ein Alerting (E-Mail Report), basierend auf den Kontaktdaten aus der API Datei (gecachte letzte Version) zu aktivieren. Gerne kann ich auch die Erstellung von "Delete PRs" in https://github.com/freifunk/directory.api.freifunk.net per github API implementieren, wenn, z.B. das Problem nach dem Mindestwert (z.B. 7 Tagen) nicht behoben ist (unabhängig davon, ob ein Alert aktiviert wurde oder nicht). Der Source Code wird natürlich noch auf github.com veröffentlicht. Mittelfristig würde ich es begrüßen diesen in eine Subdomain von freifunk.net zu installieren und eine Übergabe an die Admins von freifunk.net zu machen, um die langfristige Verfügbarkeit sicherzustellen.

Ich freue mich auf Euer Feedback zu diesem Prozessvorschlag und zum o.g. Monitoring Tool.

[andibraeu]

• alle Einträge werden bei DELETES überprüft: das ist einerseits aus der Not geboren, dass Travis trotzdem läuft und etwas tun will. Das war bisher aber kein großes Problem, DELETES gibt es recht selten und werden meist auch von den Betreibern selbst erstellt
• Monitoring vs. travis: das stimmt schon, Travis wurde nie als Monitoring für die API-Files gedacht, sondern nur als eine Hilfe, ob Communityfiles zum Zeitpunkt einer Änderung korrekt sind. Anfangs wurden auch immer alle Files geprüft, später habe ich das implementiert, dass nur das Diff geprüft wird.
• etwas Monitoring haben wir unter https://api-viewer.freifunk.net gebaut. @OLeier hatte sich auch schon tiefer damit auseinander gesetzt.
• dein Monitoringansatz finde ich gut, das können wir später, wenn du es für "fertig" oder "fast fertig" hältst auch unter einer Subdomain von freifunk.net stellen. Wenn ihr es trotzdem betreiben könnt wäre das toll, die freifunk.net-Admins betreiben jetzt schon ziemlich viel
• über das automatische Erstellen von delete PRs müssten wir noch detaillierter reden

[OLeier]

Super, dass sich noch jemand mit dem Qualitätsgedanken auseinandersetzt. Danke.

Euer Kommentar zum API Viewer ist nicht ganz richtig:

• Mtime zeigt den letzten merge in die summary,
• Etime zeigt den letzten Leseversuch im Fehlerfall und
• Error den Fehlertext.

Zugegeben (nur) für Insider. Ich bin aber froh, dass diese Daten vorhanden sind. Natürlich könnte man auch die Anzeige ändern. Auf meine Anregung habe ich einen Link zum Quelltext bekommen. Interesse an einer Änderung hätte ich schon, nur keine Zeit ...

Aufgrund der Summary Daten (https://api.freifunk.net/data/ffSummarizedDir.json) verschicke ich alle 1-2 Monate Mails - mit gemischtem Erfolg. Ein Mail ist im Forum gelandet: "https://forum.freifunk.net/t/aw-freifunk-api-directory-neukirchen-vluyn-eure-api-datei-ist-seit-dem-17-03-2019-nicht-lesbar/20506/2". Außerdem gibt es noch 2 weitere Beiträge zu diesem Thema von mir: "https://forum.freifunk.net/t/freifunk-api-montoring-statistik-umfrage/20540" und "https://forum.freifunk.net/t/freifunk-api-verzeichnis-loeschen-veralteter-eintraege/20964". Der nächste delete PR ist in Vorbereitung - 11 Einträge im Alter von 1-3 Jahren. Mails verschicken ist im übrigen heute so eine Sache. Die Porno Erpresser sind mir schon auf den Fersen.

Eine Woche bis zum Löschen mag auf der einen Seite berechtigt sein. Auf der anderen Seite wurde ich schon darauf hingewiesen, dass Freifunk ein Hobby Projekt ist und in der Freizeit bearbeitet wird. Mangels andersartigem Feedback habe ich mir erst einmal 1 Jahr als Grenze gesetzt - Kommunikation über o.g. Mail und das Forum. Evtl. sind 6 Monate sinnvoll.

Weitere Aktivitäten meinerseits auf "https://www.ib-leier.net/rss/FreifunkApiResult.html" bzw. "https://www.ib-leier.net/freifunk.htm".

Im Prinzip sind Tools vorhanden - müssten überarbeitet werden - auch das Schema. Der Standard für das Datumformat nützt im Kommentar wenig. 18x wird "CEST" als Zeitzone angegeben statt "+02:00". Bei Links fehlt das Protokoll (HTTP(S), FTP). Bei MailAdressen steht ein Link auf die Liste. Im Forum werden viele andere Themen diskutiert - das API Verzeichnis kaum.

[christian-weiss]

@OLeier danke. So viel toller Input. Ich pick mir mal was raus, womit ich anfange:

Leider hat auf dieses Thema (https://forum.freifunk.net/t/freifunk-api-montoring-statistik-umfrage/20540) noch niemand reagiert. Ich mache mal den Anfang, jedoch lieber hier zentral im Ticket, statt meine Ideen überall (unauffindbar) zu verstreuen...

zu 1 "a") Auch wenn JSON Dateien von Menschen gelesen werden können, sind sie dennoch in den aller meisten Fällen für den Datenaustausch zwischen Anwendungen gedacht. Das Freifunk Community Directory (Community Registry), sowie die verlinkten Community API Dateien dienen in erster Line der Verarbeitung durch Anwendungen (Community Karte, Node Karte, API Viewer, API Generator, etc.). Kaum ein Mensch wird eine Community Datei manuell öffnen, um z.B. die Kontaktdaten einer Community rauszulesen. Menschen machen das über die Tools, außer vielleicht Entwickler und Admins, die debuggen, experimentieren, ad-hoc was fixen oder Scripte / Tools implementieren. Der Normalo verwendet da eher den API Generator, etc.

zu 1 "b") Ein "Freifunk JSON Schema" gibt es zum Glück schon. Es unterliegt einer Evolution. Aktuelle Versionsnummer des Schemas ist 0.4.14.
https://github.com/freifunk/api.freifunk.net/blob/master/specs/0.4.14.json
Da Freifunk Schema wird ich noch weiter entwickeln. Je eindeutiger die Felder zu belegen sind, desto weniger "Sonderfälle" müssen die Entwickler von Client-Tools berücksichtigen. BTW: Mein Freifunk Community Registry Quality Assuance Report (http://community-registry.ff-hamm.de/) validiert alle Dateien gemäß dem jeweiligem Freifunk JSON Schema (weitere Releases folgen).

zu 2) Hier sollten wir unterscheiden. High-Level Probleme, wie "Datei kann nicht abgerufen werden" (z.B. Server Down, SSL Zertifikat abgelaufen, HTTP 404 File Not Found, ist keine JSON Datei) sollten zu "unaufgeforderten, automatisierten E-Mails" führen. Verzögerungen sind im Alerting grundsätzlich Bad Practice - Feedback-Loop kurz halten! Auf der anderen Seite sollte man Flapping verhindern (Blinker-Effekt), also nur alamieren, wenn sicher ist, dass es nicht nur ein kurzzeitiger Network-Glitch war. Nach einem Alert sollte man diesen Alert für eine gewisse Zeit Silencen, also Spamming verhindern. Eine E-Mail am Tag ist sehr gebräuchlich, würde aber im Freifunk-Kontext (ist Hobby) jedoch zu störend sein. M.E. sind 7 da besser.
Bei Detail Problemen in der jeweiligen Community Datei (gemäß Freifunk JSON Schema nicht valide, ein Feld ist zwar Schema Konform aber semantisch falsch, etc.) sollten wir a) den persönlichen Kontakt suchen und Hilfestellung anbieten (ggf. mit PR gegen das Repo der jeweiligen Community) und b) ein opt-in für ein erweitertes Alerting anbieten (so wie es demnächst hier implementiert ist: http://community-registry.ff-hamm.de/ ) Zustellung per E-Mail, Details via Link zum Report.

zu 3)
Keine E-Mail, falsche E-Mail und keine Reaktion sollten m.E. zum entfernen aus dem Community Directory (Community Registry) führen. So wie es auch hier erwähnt ist: "Stark veraltete oder ungültige Dateien werden nach Rückfrage wieder entfernt." (https://github.com/freifunk/directory.api.freifunk.net).

zu 4) Keiner will Karteileichen! Da das Community Directory vermutlich je Woche mehr als 100x automatisiert abgerufen wird, sollte es möglichst aktuell sein. Aus der Sicht von Clients ist diese oft schon "stark veraltet", wenn dort zig Einträge seit mehreren Stunden / Tagen nicht funktionieren. Ich bin der Meinung das wir zur Lösung eines Problems mit einem der Einträge mindestens 7 Tage zugestehen sollten. Sollte in dieser Zeit noch nicht ein mal ein "ich arbeite dran" bzw. ein "ich leite das weiter an X" kommen, bin ich für direktes löschen des Eintrages. Wenn eine Bearbeitung im Gang ist oder angekündigt wurde würde ich die Frist um 7 Tage (auf 14 Tage) verlängern. Erneutes Verlängern (um jeweils ca. 7 Tage) auf insgesamt max. 30 Tage ist bei mind. wöchtentlichem Feedback möglich, sollte jedoch möglichst vermieden werden. Nach 30 Tagen ist definitiv das "Licht aus". Die Community kann sich dann gerne nach der Problembehebung erneut eintragen lassen. Wenn sich keiner kümmert dann kann auch keiner ernsthaft traurig sein, wenn er "raus" ist.

[christian-weiss]

etwas Copy&Paste aus: https://forum.freifunk.net/t/die-freifunk-api-aktuell-halten/6504/4
bzgl.: das Feld "state.lastchange" aktuell halten bzw. auswerten:

Wer eine NodeList hat, hat üblicher Weise auch ein Script, daß das Feld "state.nodes" (Aktive Nodes) regelmäßig automatisiert und dabei auch das Datumsfeld frisch hält.

Für alle Communities die keine NodeList ausliefern (wo das z.B. eine andere Community aus der Meta Community zentral macht), da wäre es ok, wenn es kein automatisiertes Aktualisieren gibt. Dort würde das Feld quasi der letzten Änderung oder dem letzten Review entsprechen. Bei vorhandener NodeList könnte man auf ein Problem schließen, wenn das Datumsfeld älter als 24 Stunden ist. Bei manuellen Dateien (ohne NodeList) sind vielleicht 3-6 Monate akzeptabel. Es sollte keiner gezwungen sein, ohne nodeList zu haben, es zu automatisieren - denn das würde unsere Fähigkeit Probleme zu Entdecken einschränken.

[christian-weiss]

@OLeier ich hatte vor Kurzem "Freifunk Hagen" und "Funkfeuer Wels" (AT) auf einen Fehler im Feld "location.address.Zipcode" aufmerksam gemacht. Hagen hat das sogar schon gefixed.

[christian-weiss]

Meine aktuelle Statistik:

CONNECTION ISSUES: 
- Operation failed :  4
- Connection timed out :  19
- DNS Resolution Issue :  3
- Bad Request :  1
- Connection refused :  1
Total: 28

28 requests kommen also gar nicht erst an (Verbindungsprobleme).

FINAL HTTP STATUS CODES: 
- Code 200 :  403
- Code 404 :  9
- Code 400 :  1
- Code 503 :  1
Status Problems: 11
Total: 414 

11 responses sind schon mal kein JSON.
Und weitere 4 sind gemäß Freifunk JSON Schema nicht valide.

2 Einträge zeigen auf den selben Endpunkt/URL.

Und ziemlich unnötige Redirects haben wir auch noch:

HTTP STATUS WARNING:
WARNING: HTTP Status Code 301: 37 
WARNING: HTTP Status Code 302: 5

Von den semantischen Fehlern, die das Freifunk JSON Schema gar nicht erkennt (Du hast bereits einige erwähnt) haben wir Hunderte.

Mehr dazu im nächsten Release von http://community-registry.ff-hamm.de/

@OLeier die Datei https://api.freifunk.net/data/ffSummarizedDir.json finde ich übrigends extrem hilfreich - gutes Langzeitgedächtnis!

[OLeier]

@christian-weiss jetzt habe ich jede Menge Info's zu verarbeiten ...

Als Resonaz auf ca. 35 Mails kommt ca. 2x "Danke für den Hinweis ...". Es ist nicht so, dass gar nichts passiert. Aber irgendwie kommt auf einen behobenen Fehler ein Neuer hinzu.

Bisher werden die Mails zwar automatisch erstellt, das Abschicken behalte ich mir manuell vor - was aber leider zu größeren Abständen führt. Ein vollautomatisches Verschicken ist geplant. Insofern sollten wir in Kontakt bleiben, um Doppel zu vermeiden.

Der Vollständigkeitshalber wollte ich noch erwähnen, dass ich zu der ffSummarizedDir.json nur die beiden error Felder beigesteuert habe.

[andibraeu]

die Summary wird stündlich erzeugt. Unter https://api.freifunk.net/data/history/ gibt es eine stündliche History seitdem wir die Summary erzeugen

[christian-weiss]

Wie machen wir weiter? @OLeier @andibraeu

[OLeier]

Das o.g. automatische Mailing ist nach wie vor bei mir geplant - kann sich aber noch ziehen.
Alle Fehler, die älter sind als 24h, bekommen ein Mail. Wiederholung monatlich. u. evtl. eine Liste, welche öffentlich einsehbar ist. Deine in zu 4) genannte Vorgehensweise hört sich ersteinmal hart an. Wenn im Mail die Vorgehensweise angekündigt wird, wäre eine wöchentliche Wiederholung denkbar.

14 alte Einträge sind inzwischen gelöscht (> 12 Monate). Eine schrittweise Verkürzung auf 9 bzw. 6 Monate alte Einträge wäre denkbar.