repo-radar

Was macht repo-radar?

Das Dashboard ist eine einzige HTML-Datei, die von scripts/dashboard.py aus GitHub bezogen wird. Es benötigt Python 3.10+, PyYAML und die GitHub CLI (gh). Es ruft keine KI auf, kann also jeden Morgen in einem GitHub Action kostenlos neu gebaut werden.

Tabs

Tab	Was es zeigt
Plan	Nur wenn das Repository eine Plan-Datei hat. Jeder Teil des Systems als Box, wer sie besitzt und welche Elemente gebaut, in Überprüfung oder fehlend sind. Markiert Elemente, deren PR gemergt oder geschlossen ist, sowie offene PRs ohne zugehöriges Element.
Pull-Requests	Offene PRs sortiert nach Bedarf: bereit zum Mergen, benötigt Review, wartet auf den Autor, Checks fehlgeschlagen, Entwurf. "Start here" zeigt bis zu fünf.
Issues	Offene Issues: niemand dran, jemand zugewiesen, ein PR ist offen.
Grafik	Wie offene Arbeiten verknüpft sind: Plan-Box → Issue → PR, Sub-Issues, "blocked by", PRs basierend auf Branches anderer PRs.
Erledigt	PRs und Issues der letzten 90 Tage, gruppiert nach dem Release, in dem sie ausgeliefert wurden.

Es gibt zwei Möglichkeiten der Einrichtung. Frage, welche die Person möchte, falls unklar:

Weg	Für	Was hinzugefügt wird, wo
In einem Repo (init)	Jemand, der an diesem Repo arbeitet	Ein täglicher Action in diesem Repo, der die Seite für dieses Repo baut
Watchlist (init --watch)	Jemand, der mehrere Repos im Auge behält, z. B. Manager oder Lehrkraft	Ein täglicher Action in einem eigenen Repo, der eine Seite pro beobachtetem Repo plus eine Übersicht erstellt. Nichts wird den beobachteten Repos hinzugefügt

SCRIPT unten bezieht sich auf scripts/dashboard.py in diesem Skill-Ordner bzw. auf .github/dashboard/dashboard.py in einem Repository, das init ausgeführt hat.

Die Plan-Datei (optional)

Der Plan listet auf, was das System benötigt, was GitHub nicht wissen kann: Teile, für die noch niemand ein Issue oder PR erstellt hat. Das vollständige Format steht oben in scripts/dashboard_plan.py, und templates/plan.yaml ist ein Einstieg. Kurz gefasst: Gruppen von Boxen, jede Box eine Liste von Elementen, jedes Element built, simulated, pr (mit Nummer) oder missing. Boxen haben einen owner oder übernehmen den ihrer Gruppe. Standardort ist docs/plan.yaml; mit --plan für einen anderen Pfad.

Regeln

1. Zuerst berichten, nur auf Anfrage bearbeiten. Das Skript bearbeitet den Plan nie. Bearbeite ihn nur, wenn die Person dich bittet, ihren Pull-Request einzutragen.
2. Nur die eigenen Elemente der Person bearbeiten. Lasse die Elemente anderer Personen sowie die Zeile as_of in Ruhe. Offene Pull-Requests bearbeiten dann nicht alle die gleichen Zeilen.
3. Nicht built setzen, es sei denn die Person führt die wöchentliche Aktualisierung durch. Eine Person macht das einmal pro Woche, nachdem der Pull-Request gemergt wurde. Sage stattdessen "gemergt, bereit für die wöchentliche Aktualisierung".
4. Nie einen Status erfinden. Ein Element ist pr nur, wenn ein offener Pull-Request diese Arbeit erledigt. Wenn du nicht erkennen kannst, zu welcher Box ein Pull-Request gehört, frage nach.
5. Die HTML-Seite nie in den Haupt-Branch committen. Der tägliche Action behält sie in einem eigenen dashboard-Branch. Eine von Hand erstellte Seite kommt in einen temporären Ordner außerhalb des Repos (<scratch dir> unten).

Einrichtung in einem Repository

Frage vor dem Schreiben in einem Durchgang:

• Möchte das Team einen Plan? Falls ja, wo (Standard docs/plan.yaml), und existiert bereits einer? Jede Datei im obigen Format funktioniert, also kann ein bestehendes bleiben.
• Zu welcher Uhrzeit soll das Dashboard neu gebaut werden? Der Action verwendet UTC; Standard 11:00 UTC täglich.

Dann, vom Hauptordner des Repos aus:

python SCRIPT init                                   # Skripte + täglicher Action
python SCRIPT init --with-plan                       # ... und eine Startdatei docs/plan.yaml
python SCRIPT init --plan pfad/zu/plan.yaml          # ... mit einem bestehenden Plan

init schreibt .github/dashboard/ (die Skripte) und .github/workflows/dashboard.yml und weigert sich, vorhandene Dateien zu überschreiben. Dann:

1. Baue die Seite einmal lokal (nächster Abschnitt) und zeige sie, damit die Person sieht, dass es funktioniert.
2. Falls du eine Start-Plan-Datei geschrieben hast, fülle sie mit der Person: Gruppen, Boxen, Besitzer und eine people-Liste, die jedem Besitzernamen den GitHub-Login zuordnet.
3. Sage ihnen, was sie committen sollen (die von init geschriebenen Dateien und den Plan) und dass sie es nach dem Merge in den Default-Branch sofort über den Actions-Tab ausführen können ("Dashboard", dann "Run workflow").
4. Erkläre, wie sie es jeden Morgen ansehen: git fetch origin dashboard && git show origin/dashboard:index.html > dashboard.html, dann dashboard.html öffnen. Bei öffentlichen Repos können sie stattdessen GitHub Pages für den dashboard-Branch aktivieren und erhalten eine Webadresse.

Wenn der Action mit "Permission denied" beim Push fehlschlägt, schränkt das Repository oder die Organisation ein, was Actions tun dürfen: Einstellungen → Actions → Allgemein → Workflow-Berechtigungen, "Lesen und Schreiben". Die Person, nicht du, ändert diese Einstellung.

Einrichtung einer Watchlist (mehrere Repositories)

Frage in einem Durchgang: welche Repos überwacht werden sollen (als Besitzer/Name), ob eines seinen Plan an einem anderen Ort als docs/plan.yaml hat, welches Repository der Person die Watchlist enthalten soll (ein neues, leeres Repository ist in Ordnung) und zu welcher Uhrzeit (UTC) neu gebaut werden soll.

Baue die Seiten einmal vor dem Schreiben, damit die Person sie sieht:

python SCRIPT watch --list <scratch dir>/watchlist.yaml --out <scratch dir>/radar

Öffne index.html in diesem Ordner. Ein Repository, das nicht gelesen werden kann, zeigt seinen Fehler in seiner Zeile an, ohne die anderen zu stoppen – normalerweise ein Tippfehler im Namen oder ein privates Repo.

Dann, im Repository, das die Liste enthalten wird:

python SCRIPT init --watch            # Skripte, watchlist.yaml und .github/workflows/radar.yml

Schreibe die Repos der Person in watchlist.yaml und teile ihnen dann mit:

1. Was sie committen sollen (die Dateien, die init --watch geschrieben hat), und dass sie es nach dem Merge in den Default-Branch sofort über den Actions-Tab ausführen können ("Radar", dann "Run workflow").
2. Private Repos benötigen einen Token. Der Action kann öffentliche Repos und sein eigenes Repository lesen, sonst nichts. Um private Repos zu überwachen, erstellt die Person einen GitHub-Token, der sie lesen kann, und speichert ihn als Secret namens RADAR_TOKEN im überwachenden Repository (Einstellungen → Secrets and variables → Actions). Sie erledigen das selbst; frage nie nach dem Token oder füge ihn irgendwo ein.
3. Wie sie es jeden Morgen ansehen: mkdir -p radar && git fetch origin dashboard && git archive origin/dashboard | tar -x -C radar, dann radar/index.html öffnen.

Um später ein Repository hinzuzufügen oder zu entfernen, bearbeite watchlist.yaml; nichts anderes ändert sich.

Aktualisieren der Skripte in einem Repository

init kopiert die Skripte in das Repository, so dass ein Repository die Version behält, die es erhalten hat, bis jemand aktualisiert. Wenn die Person darum bittet, repo-radar in einem Repository zu aktualisieren, oder die Skripte dieses Skills neuer sind als die des Repos, führe vom Hauptordner des Repos aus:

python scripts/dashboard.py update        # diese Kopie des Skills, nicht .github/dashboard/

Es ersetzt nur die Skripte in .github/dashboard/ und gibt an, welche geändert wurden. Der Action, die Watchlist und der Plan bleiben, wie die Person sie hinterlassen hat. Sage ihnen dann, .github/dashboard/ zu committen.

Jetzt anschauen

python SCRIPT build --out <scratch dir>/dashboard.html

Führe es innerhalb des Repos aus (oder mit --repo owner/name). Schreibe die Seite in einen temporären Ordner außerhalb des Repos, damit sie nie committed wird, und zeige sie der Person. Erkläre, was sie sagt, beginnend mit der "Start here"-Karte und allen gelben Tags im Tab Plan. Jede Zahl trägt ihr Körnchen: "12 von 16 offenen Pull-Requests benötigen Review", nicht "12 benötigen Review".

Wo bin ich (eine Person, gegen den Plan)

Du benötigst zwei Namen: den Besitzernamen, wie der Plan ihn schreibt, und den GitHub-Login. Wenn die people-Liste des Plans den Login enthält, mit dem gh angemeldet ist, findet das Skript den Namen selbst. Andernfalls frage nach und übergib --owner "Name". Übergib --login nur, wenn die Person nach jemand anderem fragt.

Führe es zweimal aus, wenn die Person in einem Pull-Request-Branch ist. main zeigt, was das Team heute sieht; der Branch zeigt, was dieser Pull-Request ändern wird:

git fetch origin
python SCRIPT me --ref origin/main
python SCRIPT me

Der Bericht hat vier Tabellen:

Tabelle	Was sie der Person sagt
Deine Boxen	Für jede Box, die sie besitzen oder in der sie einen PR haben: wie viele Elemente gebaut, simuliert, in einem PR oder fehlend sind
Noch fehlende Elemente	Ihre nächste Arbeit, Box für Box
Als pr markierte Elemente, gegen GitHub geprüft	Ein offener PR benötigt nichts. Ein gemergter PR ist bereit für die wöchentliche Aktualisierung. Ein geschlossener, nicht gemergter PR bedeutet, dass das Element zurück auf missing gesetzt werden sollte
Deine offenen Pull-Requests ohne Element im Plan	Arbeit, die der Plan noch nicht zeigt

Erkläre es in dieser Reihenfolge: was erledigt und in Review ist; welche Pull-Requests dem Plan fehlen und in welche Box sie wahrscheinlich gehören; jedes Element, dessen PR ohne Merge geschlossen wurde; das erste fehlende Element als wahrscheinliche nächste Aufgabe.

Pull-Request in den Plan eintragen (nur auf Anfrage)

Arbeite im Pull-Request-Branch der Person, nicht auf main.

1. Finde die Pull-Request-Nummer: gh pr view --json number,title.
2. Finde das Element, das der Pull-Request baut. Lese die Boxen der Person im Plan.
   • Wenn ein Element die Arbeit bereits beschreibt, ändere seinen Status auf pr und füge pr: <nummer> hinzu.
   • Wenn kein Element vorhanden ist, füge eines in die richtige Box ein: {status: pr, pr: <nummer>, text: "<was es baut>"}. Halte text kurz und klar. Frage die Person, welche Box, wenn es nicht offensichtlich ist.
3. Überprüfe, ob der Plan noch lädt: python SCRIPT build --out <scratch dir>/check.html. Wenn nicht, stoppt es mit einer Meldung, die den Fehler benennt.
4. Führe me erneut aus. Der Pull-Request sollte jetzt unter "Items marked pr" stehen, nicht unter "no item on the plan".
5. Committe die Plan-Datei im Pull-Request der Person.

Wöchentliche Aktualisierung (nur für die Person, die sie durchführt)

Baue die Seite auf main oder führe me --ref origin/main einmal für jeden Besitzer aus. Dann erstelle in einem Pull-Request:

• Markiere jedes Element, dessen Pull-Request gemergt wurde, als built oder simulated, falls die gemergte Arbeit ein Stub, Fake oder Gerüst ist. Der Tab Plan markiert diese als "merged".
• Setze jedes Element, dessen Pull-Request ohne Merge geschlossen wurde, zurück auf missing.
• Liste die offenen Pull-Requests ohne Element (letzter Abschnitt des Plan-Tabs) in der Beschreibung des Pull-Requests auf, damit ihre Besitzer sie platzieren können. Rate nicht die Boxen.
• Setze as_of auf den main-Commit und das Datum, das du geprüft hast.

Ohne Netzwerkzugriff

python SCRIPT fetch --out data.json speichert, was GitHub gesagt hat; build --data data.json und me --data data.json arbeiten dann offline. Tests verwenden dies.