Mode d'emploi

Ce que ça fait, à quoi ça sert ?

Outil permettant de produire une vue d'ensemble de l'avancement des travaux GitHub/Classroom pour l'ensemble d'une classe d'étudiants.

La vue d'ensemble est générée au format markdown dans un nouveau fichier qui sera tout simplement ajouté au projet (par exemple Suivi_D400_20250224_104638.md s'il s'agit du module D400). La date et heure inversée y est utilisée. Du coup, en plus de la vue d'ensemble, on disposera aussi si souhaité d'un historique d'avancement.

Par exemple ceci (les logos montrent l'état et sont aussi un lien direct vers le repo) :

Et ces fichiers seront automatiquement ajoutés au projet et classés dans l'arborescence :

Configuration

La configuration se fait dans des fichiers .env.

Configuration générale

À la raçine, le fichier config.env doit contenir :

# votre token github
GITHUB_TOKEN = xxxxxxxxxxxxx
# module a traiter (=config spécifique à charger/utiliser)
MODULE = D400

Configuration d'un module spécifique

Sous /config, pour chaque MODULE souhaité, il vous faudra :

• un fichier nommé MODULE.env (par exemple 666.env si le module se nomme 666) doit contenir

# le nom affichable du module, utilisé aussi dans le nom de fichier .MD généré
module = D400

# organisation contenant les repos des apprentis
organisation = emf-info-24-25-2

# Le titre qui sera mis dans le fichier de vue d'ensemble généré
md_title = Suivi classroom 2024_2025 - 300212 - D400

• un fichier nommé MODULE_students.env (par exemple 666_students.env si le module se nomme 666) doit contenir

# Attention : c'est leur "vrai nom" sur GitHub qui doit être utilisé, car c'est celui-là
# qui est utilisé par classroom pour générer le nom de leur repos (on les voit dans les rosters)
NOM1 = NomUtilisateurSurGitHub
NOM2 = NomUtilisateurSurGitHub
NOM3 = NomUtilisateurSurGitHub
...
NOM20 = NomUtilisateurSurGitHub

• un fichier nommé MODULE_projects.env (par exemple 666_projects.env si le module se nomme 666) doit contenir

# Liste des noms de projets à suivre
# Nom court (pour entête du tableau) = nom classroom (terminé par un -)
D01 = d400-d01-alcoolos-
D02 = d400-d02-personneetcopains-
D03 = d400-d03-unpourtous-
....
D13 = d400-d13-enums-
EX01 = d400-ex01-lechien-
EX02 = d400-ex02-eleves-
....
EX12 = d400-ex12-gestionemployes-
EX66 = d400-ex66-jeutouchecoule-
....
F08 = d400-f08-personne-
RP = d400-rp-

Threads pour aller plus vite

Pour établir une vue d'ensemble de plusieurs travaux (T) pour plusieurs apprentis (N), un nombre important d'appels à l'API GitHub est nécessaire (T x N x 2-5).

Cela prend du temps, raison pour laquelle ces appels aux API sont parallélisés à l'aide d'un pool de threads (64) afin de booster le temps d'exécution globalement nécessaire.

Attention : GitHub impose des limites d'appels à leurs API (~5000 appels par heure, voir https://docs.github.com/fr/rest/using-the-rest-api/rate-limits-for-the-rest-api?apiVersion=2022-11-28).

Comment générer son "token personnel" GitHub

Pour vous identifier et authentifier face aux apis GitHub, il vous faudra un PAT. Il s'agit d'un token personnel (Personal Access Token, "PAT") qui doit être créé sur le site GitHub, une alternative sécuritaire fortement recommandée à l'utilisation du user/password GitHub pour des interactions automatisées comme celles-ci avec l'API GitHub.

Étapes pour générer son propre PAT de durée/validité limitée :

• Connecte-toi à ton compte GitHub
• Accède aux paramètres (Settings) :
  • Clique sur ta photo de profil en haut à droite de la page
  • Sélectionne Settings dans le menu déroulant
• Accède à la section Developer settings tout en bas dans la barre latérale à gauche
• Dans cette section clique sur Personal access tokens dans la barre latérale à gauche
• puis sur Tokens (classic) pour accéder à la liste de tes tokens existants ou en générer de nouveaux
• Clique sur le bouton Generate new token et choisis l'option New personal access token (classic)

Configurer les permissions du token :

• Donne un nom à ton token pour t'en rappeler facilement, par exemple GitHubClassroomsOverviewGenerator
• Choisis une durée d'expiration pour ton token (7 jours suffiront amplement).
• Sélectionne le scope nécessaire pour que ce projet puisse fonctionner :
  • coche le scope repo afin d'avoir le droit de cloner les repos
• Génère le token
• Copie et stocke ton token dans le fichier config.env.

N.B. Tu ne pourras plus voir ce token après avoir quitté cette page, donc assure-toi de bien l'avoir noté dans la constante et ne pas le diffuser. Ce token sera utilisé dans tes requêtes API GitHub pour authentifier tes accès à tes repositories.

Exécution depuis VSC

S'agissant d'un projet Java Maven, tout devrait normalement se faire automatiquement au 1er run (la première fois il téléchargera les librairies Java nécessaires référencées par le fichier pom.xml).

En cas de soucis, lancez la commande Maven suivante mvn clean install dans le terminal du projet VSC pour le forcer à nettoyer le projet et à télécharger tout le nécessaire pour son exécution.

Une fois terminé, il vous suffira de consigner les fichiers zip générés (sharepoint).

N.B. Si Maven n'est pas installé sur votre poste => https://maven.apache.org/

Exemple d'exécution

L'exécution prends un peu de temps (qui dépendra du nombre d'apprentis et de projets à interroger). Voici à quoi ressemble l'output pour l'organisation d400 :

=====================================================================================
GitHubClassroomOverviewGenerator - Written by Paul Friedli
-------------------------------------------------------------------------------------
Récupération de la liste des repos de [emf-info-24-25-2] en cours...
Un total de 467 repos ont été trouvés pour l'organisation [emf-info-24-25-2] !
Seuls 318 sont concernés par cette vue d'ensemble !
Vérification de l'état des repos GitHub avec un pool de [64] threads...
 - état du repo [emf-info-24-25-2/d400-d06-datesheureslisibles-user1-Emf] établi !
 - état du repo [emf-info-24-25-2/d400-d04-nombreslisibles-user2-EMF] établi !
 - état du repo [emf-info-24-25-2/d400-ex02-eleves-user2-EMF] établi !
 - état du repo [emf-info-24-25-2/d400-d02-personneetcopains-user3-emf] établi !
 - état du repo [emf-info-24-25-2/d400-d01-alcoolos-user3-emf] établi !
 - état du repo [emf-info-24-25-2/d400-d03-unpourtous-user2-EMF] établi !
 - état du repo [emf-info-24-25-2/d400-d05-chaussures-user2-EMF] établi !
 - état du repo [emf-info-24-25-2/d400-d01-alcoolos-user2-EMF] établi !
 - état du repo [emf-info-24-25-2/d400-ex05-identificationcodesource-user3-emf] établi !
...
...
...
...
 - état du repo [emf-info-24-25-2/d400-ex10-vinsetspiritueux-user4-emf] établi !
 - état du repo [emf-info-24-25-2/d400-e0-formative-user4-emf] établi !
 - état du repo [emf-info-24-25-2/d400-rp-user4-emf] établi !
 - état du repo [emf-info-24-25-2/d400-d09-uml-is-easy-user5-emf] établi !
 - état du repo [emf-info-24-25-2/d400-e0-formative-user5-emf] établi !
 - état du repo [emf-info-24-25-2/d400-rp-user5-emf] établi !
 - état du repo [emf-info-24-25-2/d400-ex05-identificationcodesource-user5-emf] établi !
 - état du repo [emf-info-24-25-2/d400-ex04-devinemonnombre-user5-emf] établi !
Vérification de l'état des repos GitHub terminé !
Génération du fichier de vue d'ensemble [./classroom-overview/D400/Suivi_D400_20250410_093634.md] : terminé !
=====================================================================================