github-readme-stats: Was die Statistikkarten leisten und warum der Fork ruft

Was github-readme-stats in ein Profil-README einbettet

Ein Profil-README auf GitHub ist statisch: Es zeigt, was jemand über sich schreibt, aber nicht, was diese Person im vergangenen Jahr beigetragen hat. github-readme-stats füllt diese Lücke mit einem SVG, das beim Aufruf entsteht und als Bild in Markdown eingebunden wird. Die README beschreibt den Zweck knapp mit dem Satz Get dynamically generated GitHub stats on your READMEs! Der Aufruf läuft über die gehostete Instanz unter github-readme-stats.vercel.app, der Benutzername wird als Parameter übergeben.

Fünf Kartentypen sind dokumentiert. Die Statistikkarte bildet Sterne, Commits, Pull-Requests, Issues und Beiträge ab. Die Top-Sprachen-Karte zeigt, welche Sprachen in den eigenen, nicht geforkten Repositories den meisten Code stellen; die README weist ausdrücklich darauf hin, dass daraus kein Kompetenzniveau abzulesen ist. Die Pins-Karte über den Endpunkt api/pin stellt ein einzelnes Repository dar und hilft damit über die sechs von GitHub erlaubten Anpinnungen hinaus, die Gist-Karte über api/gist entsprechend einen Gist. Die WakaTime-Karte holt über api/wakatime Codierzeit aus einem öffentlichen WakaTime-Profil, wofür dort Display code time publicly sowie Display languages, editors, os, categories publicly aktiviert sein müssen.

Der Rangkreis von github-readme-stats: S bis C nach japanischem Schema

Der auffälligste Teil der Statistikkarte ist der Rang. Die README listet die Stufen S (top 1%), A+ (12.5%), A (25%), A- (37.5%), B+ (50%), B (62.5%), B- (75%), C+ (87.5%) und C (everyone). Als Vorbild nennt sie das japanische Notensystem. Der globale Perzentilwert entsteht als gewichtete Summe der Perzentile einzelner Kennzahlen, namentlich Commits, Pull-Requests, Reviews, Issues, Sterne und Follower.

Wie die Gewichte gesetzt sind, beschreibt die README über die kumulative Verteilungsfunktion der Exponentialverteilung und der logarithmischen Normalverteilung. Nachvollziehen lässt sich die Rechnung in der Datei src/calculateRank.js im Branch master. Für die Bewertung heißt das: Der Rang ist eine statistische Schätzung gegen eine gedachte Gesamtheit und kein Wert, den GitHub vergibt. Wer einen Rang in sein Profil stellt, zeigt eine Vergleichsrechnung, keine Prüfung durch die Plattform.

URL-Parameter der github-readme-stats-Karten: username, theme, cache_seconds

Gesteuert werden die Karten über Abfrageparameter. Der wichtigste ist username, den die README mit dem Hinweis Change the ?username= value to your GitHub username zum Austausch auffordert. Für das Aussehen nennt die Projektbeschreibung den Parameter theme, gefolgt von einem eingebauten Themanamen; die README merkt an, dass neue Themen aus Wartungsgründen nicht mehr ergänzt werden. Für Farben, Hintergrund, Rahmen, Rahmenradius, Gebietsschema und Cache-Dauer stellt die README eine gemeinsame Optionsliste bereit, in der cache_seconds die Gültigkeit einer erzeugten Karte festlegt und damit die Last auf der Instanz dämpft.

Dazu kommen kartenbezogene Schalter. Einzelne Statistiken lassen sich ausblenden, zusätzliche Werte wie Reviews oder gemergte Pull-Requests einblenden, eigene Titel setzen. Die Sprachkarte kennt die Layouts normal, compact, donut, donut-vertical und pie, erlaubt das Ausschließen einzelner Repositories, das Verbergen von Sprachen und das Anzeigen weiterer Sprachen, und ordnet sie über einen Algorithmus, für den size_weight und count_weight mit jeweils 0.5 als Ausgangslage dokumentiert sind. Eigene Titel und Sprachnamen müssen URI-escaped übergeben werden.

Selbst hosten statt Best-Effort-Instanz: PAT, Vercel und GitHub Actions

Die öffentliche Instanz unter github-readme-stats.vercel.app/api ist nach eigener Aussage nur nach bestem Bemühen verfügbar und kann durch Ratenbegrenzungen sowie Lastspitzen unzuverlässig werden; die README verweist dazu auf Issue #1471. Für verlässliche Karten nennt sie zwei Wege: eine eigene Bereitstellung, etwa auf Vercel, oder die Erzeugung der Karten per GitHub-Actions-Workflow im eigenen Profil-Repository. Caching dient laut README der Stabilisierung, ersetzt aber keine eigene Instanz.

Für eigene Daten braucht es einen GitHub Personal Access Token. Ohne eigenen Token zeigt die Statistikkarte laut README nur Werte aus öffentlichen Repositories, also Sterne, Commits und Pull-Requests in öffentlicher Sichtbarkeit; private Beiträge erscheinen erst mit einer eigenen Instanz samt eigenem Token. Die README führt einen Abschnitt Available environment variables, deren Namen im vorliegenden Auszug nicht enthalten sind und die deshalb in der aktuellen Fassung unter Deploy on your own nachgeschlagen werden müssen. Wer selbst hostet, sollte die Kopie aktuell halten, wofür die README den Abschnitt Keep your fork up to date bereithält.

Wartungsstopp bei github-readme-stats: GitHub Stats Extended als Nachfolger

Der wichtigste Punkt steht ganz oben im README und ist als Warnung gesetzt: Das Repository wird nicht mehr gepflegt. Als Nachfolger verweist die Projektseite auf GitHub Stats Extended im Account stats-organization, einen aktiv gepflegten Fork mit zusätzlichen Funktionen und verbesserter Stabilität. Als zweite Möglichkeit nennt sie GitHub Readme Stats Action im selben Account. Die restliche Dokumentation liegt hinter einem ausklappbaren Bereich, der ausdrücklich als veraltet und nur noch als Referenz gedacht gekennzeichnet ist.

Wer heute eine Karte einbindet, sollte den Fork prüfen, statt auf Korrekturen am Ursprungsrepository zu warten. Das gilt auch für offene Wünsche: Die README bittet darum, Issues und Pull-Requests per Hochstimme zu priorisieren, weil ein kleines Team anhand eines Top-Issues-Dashboards arbeitet (Issue #1935). Zum Zeitpunkt der Erhebung stehen 293 offene Issues im Archiv, veröffentlichte Release-Tags fehlen; Fortschritt lässt sich damit nur über den Commit-Verlauf verfolgen und nicht über Versionen festmachen.

Was 79.845 Sterne über github-readme-stats aussagen und was nicht

Zur Einordnung der Verbreitung: Das Repository verzeichnet 79.845 Sterne und 37.166 Forks, ist in JavaScript geschrieben, unter MIT lizenziert und nutzt master als Standardbranch. Der ungewöhnlich hohe Fork-Anteil erklärt sich aus der Betriebsart, denn Selbsthosting verlangt im Regelfall eine Kopie des Repositories. Die MIT-Lizenz erlaubt solche Kopien auch in kommerziellen Profilen, solange der Lizenzvermerk erhalten bleibt; sie schließt jede Gewährleistung aus. Fällt die öffentliche Instanz aus, bleibt die eigene Karte schlicht leer, ohne dass jemand haftet.

Verbreitung ersetzt keine Pflege. Für die eigene Wahl zählt eher, ob die Karte im Profil zuverlässig lädt, was sich an der Antwortzeit der Endpunkte api und api/top-langs der genutzten Instanz ablesen lässt, und ob die gezeigten Zahlen mit dem übereinstimmen, was GitHub auf der Profilseite selbst ausweist. Bleibt die Statistikkarte dauerhaft hinter einem Cache-Wert zurück oder weicht sie sichtbar ab, ist der Wechsel zum Fork oder zu GitHub Readme Stats Action die folgerichtige Konsequenz.

Redaktionelles Fazit

Für Profilbesitzer, die ohne eigenen Server eine ansehnliche Statistik zeigen wollen, bleibt github-readme-stats über die Vercel-Instanz ein bequemer Einstieg, solange gelegentlich fehlende Karten akzeptabel sind. Wer private Beiträge einbeziehen, verlässliche Antwortzeiten erreichen oder auf Korrekturen hoffen will, sollte direkt GitHub Stats Extended oder GitHub Readme Stats Action von stats-organization prüfen. Vor dem Wechsel lohnt es, die Endpunkte api und api/top-langs beider Projekte mit demselben username aufzurufen und zu vergleichen, ob Rangkreis und Sprachverteilung übereinstimmen.

Offizielle Quellen

1. Official documentation
2. Official README
3. Project repository