repo-radar

Que fait repo-radar ?

Le tableau de bord est un fichier HTML unique, généré depuis GitHub par scripts/dashboard.py. Il nécessite Python 3.10+, PyYAML, et la GitHub CLI (gh), connectée. Rien en lui n'appelle une IA, donc il peut se reconstruire chaque matin dans une GitHub Action gratuitement.

Ses onglets :

Onglet	Ce qu'il affiche
Plan	Uniquement lorsque le dépôt a un fichier plan. Chaque partie du système sous forme de boîtes, qui possède quoi, et quels éléments sont construits, en révision ou manquants. Signale les éléments dont la PR a fusionné ou a été fermée, et les PR ouvertes qu'aucun élément ne cible.
Pull requests	PR ouvertes triés par ce dont ils ont besoin : prêt à fusionner, besoin de révision, en attente de l'auteur, vérifications en échec, brouillon. « Commencez ici » en sélectionne jusqu'à cinq.
Issues	Issues ouvertes : personne ne s'en occupe encore, quelqu'un est assigné, une PR est ouverte.
Graphe	Comment les travaux ouverts sont liés : boîte du plan → issue → PR, sous-issues, « bloqué par », PR construites sur les branches d'autres PR.
Terminé	PR et issues fermés au cours des 90 derniers jours, sous la version qui les a livrés.

Il existe deux façons de le configurer. Demandez laquelle la personne souhaite si ce n'est pas clair :

Façon	Pour	Ce qu'elle ajoute, où
Dans un dépôt (init)	Quelqu'un travaillant sur ce dépôt	Une Action quotidienne dans ce dépôt, construisant la page de ce dépôt
Liste de surveillance (init --watch)	Quelqu'un surveillant plusieurs dépôts, comme un responsable ou un enseignant	Une Action quotidienne dans un de ses propres dépôts, construisant une page par dépôt surveillé plus un aperçu. Rien n'est ajouté aux dépôts surveillés

SCRIPT ci-dessous signifie scripts/dashboard.py dans le dossier de cette compétence, ou .github/dashboard/dashboard.py dans un dépôt qui a exécuté init.

Le fichier plan (optionnel)

Le plan liste ce dont le système a besoin, ce que GitHub ne peut pas savoir : les parties pour lesquelles personne n'a encore ouvert d'issue ou de PR. Le format complet se trouve en haut de scripts/dashboard_plan.py, et templates/plan.yaml est un modèle de départ. En résumé : des groupes de boîtes, chaque boîte étant une liste d'éléments, chaque élément étant built, simulated, pr (avec son numéro) ou missing. Les boîtes ont un owner, ou prennent celui de leur groupe. L'emplacement par défaut est docs/plan.yaml ; passez --plan pour un autre chemin.

Règles

1. D'abord rapporter, modifier seulement quand on le demande. Le script ne modifie jamais le plan. Ne le modifiez que lorsque la personne vous demande d'y placer sa pull request.
2. Modifiez uniquement les éléments de la personne. Laissez les éléments des autres et la ligne as_of tranquilles. Les pull requests ouvertes ne modifient pas toutes les mêmes lignes.
3. Ne marquez pas les éléments built sauf si la personne exécute l'actualisation hebdomadaire. Une personne le fait une fois par semaine, après la fusion de la pull request. Dites plutôt « fusionné, prêt pour l'actualisation hebdomadaire ».
4. N'inventez jamais de statut. Un élément est pr uniquement lorsqu'une pull request ouverte effectue ce travail. Lorsque vous ne pouvez pas dire à quelle boîte appartient une pull request, demandez.
5. Ne validez jamais la page HTML dans la branche principale. L'Action quotidienne la conserve sur sa propre branche dashboard. Une page que vous construisez manuellement va dans un dossier temporaire en dehors du dépôt (<répertoire temporaire> ci-dessous).

Configurer dans un dépôt

Demandez, d'un coup, avant d'écrire quoi que ce soit :

• L'équipe veut-elle un plan ? Si oui, où (par défaut docs/plan.yaml), et en existe-t-il déjà un ? Tout fichier au format ci-dessus fonctionne, donc un fichier existant peut rester en place.
• À quelle heure doit-il se reconstruire ? L'Action utilise UTC ; par défaut 11:00 UTC chaque jour.

Ensuite, depuis le dossier racine du dépôt :

python SCRIPT init                                   # scripts + Action quotidienne
python SCRIPT init --with-plan                       # ... et un modèle docs/plan.yaml
python SCRIPT init --plan path/to/plan.yaml          # ... en utilisant un plan existant

init écrit .github/dashboard/ (les scripts) et .github/workflows/dashboard.yml, et refuse de remplacer les fichiers qui existent. Ensuite :

1. Construisez la page une fois localement (section suivante) et montrez-la, pour que la personne la voie fonctionner.
2. Si vous avez écrit un plan modèle, remplissez-le avec la personne : groupes, boîtes, propriétaires, et une liste people mappant chaque nom de propriétaire à son identifiant GitHub.
3. Dites-lui quoi valider (les fichiers écrits par init, et le plan), et qu'après qu'il atteigne la branche par défaut, elle peut l'exécuter immédiatement depuis l'onglet Actions (« Dashboard », puis « Run workflow »).
4. Dites-lui comment le consulter chaque matin : git fetch origin dashboard && git show origin/dashboard:index.html > dashboard.html, puis ouvrez dashboard.html. Pour un dépôt public, elle peut plutôt activer GitHub Pages pour la branche dashboard et obtenir une adresse web.

Si l'Action échoue avec « Permission denied » lors du push, le dépôt ou l'organisation limite ce que les Actions peuvent faire : Settings → Actions → General → Workflow permissions, « Read and write ». La personne, pas vous, modifie ce paramètre.

Configurer une liste de surveillance (plusieurs dépôts)

Demandez, d'un coup : quels dépôts surveiller (sous forme propriétaire/nom), si l'un d'eux garde son plan ailleurs que docs/plan.yaml, quel dépôt de la personne doit contenir la liste de surveillance (un nouveau dépôt vide convient), et à quelle heure reconstruire (UTC).

Avant d'écrire quoi que ce soit, construisez les pages une fois pour que la personne les voie :

python SCRIPT watch --list <répertoire temporaire>/watchlist.yaml --out <répertoire temporaire>/radar

Ouvrez index.html dans ce dossier. Un dépôt qui ne peut pas être lu affiche son erreur sur sa ligne sans arrêter les autres : généralement une faute de frappe dans le nom, ou un dépôt privé.

Ensuite, dans le dépôt qui contiendra la liste :

python SCRIPT init --watch            # scripts, watchlist.yaml, et .github/workflows/radar.yml

Écrivez les dépôts de la personne dans watchlist.yaml, puis dites-lui :

1. Quoi valider (les fichiers écrits par init --watch), et qu'une fois qu'il atteint la branche par défaut, elle peut l'exécuter immédiatement depuis l'onglet Actions (« Radar », puis « Run workflow »).
2. Les dépôts privés nécessitent un jeton. L'Action peut lire les dépôts publics et son propre dépôt, rien d'autre. Pour surveiller des dépôts privés, la personne crée un jeton GitHub qui peut les lire, et le sauvegarde comme un secret nommé RADAR_TOKEN dans le dépôt de surveillance (Settings → Secrets and variables → Actions). Elle le fait elle-même ; ne demandez jamais le jeton et ne le collez nulle part.
3. Comment le consulter chaque matin : mkdir -p radar && git fetch origin dashboard && git archive origin/dashboard | tar -x -C radar, puis ouvrez radar/index.html.

Pour ajouter ou supprimer un dépôt plus tard, modifiez watchlist.yaml ; rien d'autre ne change.

Mettre à jour une copie des scripts d'un dépôt

init copie les scripts dans le dépôt, donc un dépôt continue d'exécuter la version qu'il a reçue jusqu'à ce que quelqu'un la mette à jour. Lorsque la personne demande de mettre à jour repo-radar dans un dépôt, ou que les scripts de cette compétence sont plus récents que ceux du dépôt, exécutez depuis le dossier racine du dépôt :

python scripts/dashboard.py update        # cette copie de la compétence, pas celle de .github/dashboard/

Il remplace uniquement les scripts dans .github/dashboard/ et indique ceux qui ont changé. L'Action, la liste de surveillance et le plan restent tels que la personne les a laissés. Ensuite, dites-lui de valider .github/dashboard/.

Consultez-le maintenant

python SCRIPT build --out <répertoire temporaire>/dashboard.html

Exécutez-le dans le dépôt (ou passez --repo propriétaire/nom). Écrivez la page dans un dossier temporaire en dehors du dépôt, pour qu'elle ne soit jamais validée, puis montrez-la à la personne. Expliquez ce qu'elle dit en mots simples, en commençant par la carte « Commencez ici » et les étiquettes jaunes sur l'onglet Plan. Chaque compte porte sa précision : « 12 des 16 pull requests ouvertes ont besoin de révision », pas « 12 ont besoin de révision ».

Où suis-je (une personne, par rapport au plan)

Vous avez besoin de deux noms : le nom du propriétaire tel qu'écrit dans le plan, et l'identifiant GitHub. Si la liste people du plan contient l'identifiant avec lequel gh est connecté, le script trouve le nom lui-même. Sinon demandez, et passez --owner "<Nom>". Passez --login uniquement lorsque la personne s'interroge sur quelqu'un d'autre.

Exécutez-le deux fois lorsque la personne est sur une branche de pull request. La branche principale montre ce que l'équipe voit aujourd'hui ; la branche montre ce que cette pull request changera :

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

Le rapport comporte quatre tableaux :

Tableau	Ce qu'il indique à la personne
Vos boîtes	Pour chaque boîte qu'elle possède ou dans laquelle elle a une pull request : combien d'éléments sont construits, simulés, dans une PR, manquants
Éléments toujours manquants	Son prochain travail, boîte par boîte
Éléments marqués pr, vérifiés sur GitHub	Une PR ouverte ne nécessite rien. Une PR fusionnée est prête pour l'actualisation hebdomadaire. Une PR fermée et non fusionnée signifie que l'élément devrait revenir à missing
Vos pull requests ouvertes sans élément sur le plan	Travail que le plan n'affiche pas encore

Expliquez-le dans cet ordre : ce qui est fait et en révision ; quelles pull requests manquent au plan, et à quelle boîte chacune appartient probablement ; tout élément dont la pull request s'est fermée sans fusion ; le premier élément manquant comme la tâche suivante probable.

Mettre une pull request sur le plan (uniquement sur demande)

Travaillez sur la branche de pull request de la personne, pas sur main.

1. Trouvez le numéro de la pull request : gh pr view --json number,title.
2. Trouvez l'élément que cette pull request construit. Lisez les boîtes de la personne dans le plan.
   • Si un élément décrit déjà le travail, changez son statut en pr et ajoutez pr: <numéro>.
   • Si aucun élément ne le fait, ajoutez-en un dans la bonne boîte : {status: pr, pr: <numéro>, text: "<ce qu'il construit>"}. Gardez text court et clair. Demandez à la personne quelle boîte, lorsque ce n'est pas évident.
3. Vérifiez que le plan se charge toujours : python SCRIPT build --out <répertoire temporaire>/check.html. Il s'arrête avec un message nommant l'erreur si ce n'est pas le cas.
4. Exécutez me à nouveau. La pull request devrait maintenant être sous « Éléments marqués pr », pas sous « sans élément sur le plan ».
5. Validez le fichier plan dans la pull request de la personne.

Actualisation hebdomadaire (uniquement pour la personne qui le fait)

Construisez la page sur main, ou exécutez me --ref origin/main une fois pour chaque propriétaire. Ensuite, dans une seule pull request :

• Marquez chaque élément dont la pull request a fusionné comme built, ou simulated si le travail fusionné est une maquette, un faux ou une ébauche. L'onglet Plan étiquette ces éléments « fusionné ».
• Remettez chaque élément dont la pull request s'est fermée sans fusion à missing.
• Listez les pull requests ouvertes sans élément (la dernière section de l'onglet Plan) dans la description de la pull request, pour que leurs propriétaires les placent. Ne devinez pas leurs boîtes.
• Mettez la ligne as_of avec le commit principal et la date que vous avez vérifiés.

Sans accès réseau

python SCRIPT fetch --out data.json sauvegarde ce que GitHub a répondu ; build --data data.json et me --data data.json fonctionnent ensuite hors ligne. Les tests utilisent cela.