percy
17. Juli 2015 um 18:39
1
Eine bitte an alle Communities: Bitte haltet die Freifunk-API aktuell!
Die Freifunk-API sammelt alle möglichen Meta-Informationen über Communites. (http://freifunk.net/services/freifunk-net-api/ )
Da derzeit eine Android und eine iOS App entwickelt wird ist aufgefallen, daß bei vielen Communities veraltete oder unvollständige Datensätze vorhanden sind. Insbesondere sei ein direkter Link zur nodelist.json erwähnt.
Vielen Dank!
7 „Gefällt mir“
Wenn man nun die „Pflicht“ einführen würde, ein Datumsfeld aktuell zum halten („max 6 Monate“), dann werden sich die Leute dafür auch nur cronjobs bauen oder die Datei gleich dynamisch aus einem Script generieren lassen.
eriu
19. Juli 2015 um 16:01
4
die aktuellste Version der API findet man im github unter GitHub - freifunk/api.freifunk.net: Freifunk Community API .
Alternativ kann auch gerne den Generator nutzen der unter http://freifunk.net/api-generator/ erreichbar ist.
@percy Dein Appell ist richtig und wichtig. 100% Unterstützung.
@adorfer es gibt bereits Scripts die z.B. automatisiert das Feld „state.nodes“ (Aktive Nodes) regelmäßig aktualisieren und dabei auch das Datumsfeld frisch halten. 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.
Ich versuche gerade alle Ideen zum Thema Qualitätssicherung der Community Registry (Community Directory) zusammen zu tragen und würde mich freuen, wenn Ihr hinzukommt:
opened 05:38AM - 24 Aug 19 UTC
Ich finde es super, dass Travis-CI jeden PR prüft.
Sogar, dass bei neuen lokale… n 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.