Robbinaer

Auf der Entwickler-Plattform GitHub findet sich längst nicht nur Software-Quellcode, sondern auch jede Menge Dokumentationsmaterial. Dies beschränkt sich jedoch nicht nur auf projektbegleitende Dokumentationen. Manche Projekte haben sich darauf spezialisiert, Entwicklern und Nutzern im manchmal unübersichtlichen Software-Dschungel eine helfende Hand zu reichen. Eine beliebte Anlaufstelle, um sich auf GitHub zurechtzufinden, sind dabei die sogenannten Awesome-Listen. Hierbei handelt es sich um Dokumentationsprojekte, die, im Gegensatz zu GitHubs automatisierter Explore-Funktion, von Hand zusammengestellte Listen mit Software, Webdiensten oder sonstigen, je nach Themengebiet passenden Dingen anbieten. Ein weithin bekanntes Beispiel ist die populäre Awesome-Selfhosted-Liste, die Software und Webdienste zusammenstellt, mit denen man sich von proprietären Anbietern lossagen kann, und stattdessen eigene Ressourcen hierfür nutzt. Auch ich pflege eine solche Liste. Awesome-Android-Accessibility richtet sich speziell an deutschsprachige blinde Android-Nutzer, und sammelt Apps, die sich durch eine gute Zugänglichkeit (Barrierefreiheit) auszeichnen.

Ein Problem bei diesen Listen ist die Tatsache, dass sich, wie im Grunde auf jeder Webseite, mit der Zeit tote Links ansammeln. Was für den Linkbereich einer privaten Webseite noch recht übersichtlich bleibt, wird bei dieser Art von Dokumentationsprojekten zur Herausforderung, können sich in den Awesome-Listen doch durchaus mal etliche hundert bis tausend Links vereinen. Da es sich jedoch um Community-Projekte handelt, kann im Grunde jeder, der einen toten Link bemerkt, diesen selbst per sogenanntem Pull-Request wieder korrigieren oder ganz aus der Liste entfernen. Dies ist natürlich eher etwas für fortgeschrittene Anwender. Eine weitere Möglichkeit, die Links auf Gültigkeit zu prüfen, sind automatisierte Linkchecker. Ganz neu ist diese Idee zwar nicht, dank GitHubs Actions-Feature lässt sie sich aber auf ein neues Level heben.

Mit sogenannten Actions kann man in GitHub-Repositories bestimmte Arbeitsabläufe (Workflows) auslösen, sobald beispielsweise ein Update des Codes vorgenommen wird. Klassisches Anwendungsszenario sind hierbei die Integritätsprüfungen, welche Software-Entwicklern zur Qualitätssicherung ihres Codes dienen. Die Abläufe werden in YAML-Konfigurationsdateien notiert, und im Verzeichnis .github/workflows hinterlegt. Auf diese Weise lässt sich auch ein URL-Checker integrieren, der bei jedem Update des Codes die Dokumentationsdateien auf tote Links prüft.

name: Test LinkChecker

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
      - name: Run LinkChecker
        uses: paramt/url-checker@master
        with:
          files: test.md
          blacklist:  https://www.github.com/paramt/this-doesnt-exist

Der Linkchecker prüft also in diesem Fall die Datei test.md, ob darin tote Links vorhanden sind. Eine Blacklist kann genutzt werden, um bestimmte Adressen von der Prüfung auszuschließen. Die Zeile "on: [push]" gibt an, dass diese Prüfung bei jeder Änderung des Codes passieren soll. Das ist für eine große Linkliste, in der täglich schon mal mehrere Updates eingepflegt werden, natürlich nicht besonders ratsam. Für diesen speziellen Fall empfiehlt es sich, den Linkchecker stattdessen nach einem Zeitplan laufen zu lassen. Genutzt wird hier die von Linux-Systemen bekannte Cron-Syntax. Aktuell lasse ich den Linkchecker in der Nacht von Samstag auf Sonntag über die Liste laufen. Mein Workflow sähe dann in etwa so aus:

name: Link Checker

on:
  schedule:
    # * is a special character in YAML so you have to quote this string
    - cron:  '0 0 * * SUN'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Check URLs
        uses: paramt/url-checker@master
        with:
          files: "README.md"

Der Linkchecker löscht allerdings nicht eigenständig die toten Links, diese Aufgabe sollte natürlich weiterhin dem Entwickler überlassen bleiben. Ist ein Link ungültig, schlägt die Aktion fehl, und man wird darüber benachrichtigt. Allerdings erhält man zunächst keine Mitteilung darüber, welcher Link nicht mehr funktioniert. Hierzu müssen die detailierten Protokollmeldungen im Ergebnisfenster angesehen oder heruntergeladen werden.

2020-05-10T00:08:00.2892582Z Collecting URLs from README.md
2020-05-10T00:08:00.2892807Z Checking URLs from README.md
2020-05-10T00:08:00.2892923Z Removing duplicate URLs from README.md
2020-05-10T00:08:00.2897924Z ✓ 200 https://play.google.com/store/apps/details?id=com.facebook.katana
[...]

Anhand der Häkchen und des HTTP-Statuscodes (200 = OK, 404 = nicht gefunden etc) oder der mit "ERR" gekennzeichneten Zeilen lässt sich schnell herausfinden, welche Adressen nicht geprüft werden konnten. Leider muss man bei umfangreichen Listen etwas intensiver mit der Blacklist arbeiten, da der Linkchecker momentan auch solche Links prüft, die eigentlich keine sind, z. B. Link-Titel oder nicht verlinkte Ausdrücke im Fließtext. Trotzdem ist dieses Tool eine nette Hilfe, um umfangreichere Linksammlungen zu pflegen. Ob bei weiter wachsender Liste dieser Workflow immer noch praktikabel ist, wird sich noch herausstellen müssen.