github-readme-stats : analyse pratique pour un usage documenté

Une instance publique et le dépôt derrière

GitHub Readme Stats est un projet JavaScript qui génère des images SVG contenant des statistiques GitHub pour un utilisateur, conçues pour être intégrées dans les README des profils GitHub. L'instance publique est hébergée sur Vercel à l'adresse https://github-readme-stats.vercel.app, et le dépôt est sous licence MIT. Selon les métadonnées du dépôt, il compte 79 816 étoiles et 36 203 forks, et la branche par défaut est master. Le slogan d'ouverture du README le décrit comme « Des statistiques GitHub générées dynamiquement pour vos README. »

Cinq types de cartes, un point de terminaison chacun

Le README documente cinq types de cartes distincts. La carte de statistiques GitHub utilise le point de terminaison api avec un paramètre username et affiche les étoiles, les commits, les pull requests, les issues et les contributions, ainsi qu'un cercle de rang qui affiche 100 moins le percentile global. La carte des langues principales utilise api/top-langs et affiche les langues avec le plus de code dans les dépôts non forkés de l'utilisateur, avec une note indiquant qu'elle ne reflète pas le niveau de compétence. GitHub Extra Pins utilise api/pin pour afficher une carte de dépôt, permettant d'épingler plus de six dépôts que GitHub autorise normalement. GitHub Gist Pins utilise api/gist pour afficher une carte de gist. Enfin, la carte WakaTime utilise api/wakatime pour afficher l'activité de codage d'un profil WakaTime public, et nécessite que « Afficher le temps de code publiquement » et « Afficher les langues, éditeurs, OS, catégories publiquement » soient activés. Chaque point de terminaison renvoie un SVG qui peut être intégré directement dans Markdown.

Personnalisation via les paramètres d'URL

Toutes les cartes acceptent un ensemble commun de paramètres de requête pour les couleurs, le fond, la bordure, le thème, le rayon des coins, la locale et cache_seconds. La couleur de fond peut être unie ou un dégradé sous la forme angle,début,fin. Il existe également des options spécifiques à chaque carte. Pour la carte de statistiques, vous pouvez masquer certaines statistiques, afficher des éléments supplémentaires comme les avis ou les PR fusionnées, inclure tous les commits, définir un titre personnalisé et changer l'icône de rang. La carte des langues principales propose cinq mises en page : normal, compact, donut, donut-vertical et pie, plus un algorithme de classement des langues avec size_weight et count_weight, avec un réglage recommandé de 0,5 et 0,5. Des thèmes sont intégrés, mais le README note que l'ajout de nouveaux thèmes est en pause pour réduire la maintenance. Les titres personnalisés et les noms de langues doivent être échappés pour l'URI.

Sources de données, mise en cache et limitations connues

Par défaut, toutes les cartes utilisent uniquement les données des dépôts publics. Pour afficher les contributions privées, vous devez déployer votre propre instance avec un jeton d'accès personnel GitHub. L'instance publique est décrite comme étant au mieux, et peut être peu fiable en raison des limites de débit et des pics de trafic. La mise en cache est utilisée pour améliorer la stabilité, avec des durées de cache par défaut variant selon le type de carte : 24 heures pour les statistiques et WakaTime, 144 heures pour les langues principales, 240 heures pour les épingles et 48 heures pour les gists. La carte des langues principales n'examine que les 100 premiers dépôts en raison des limitations de l'API GitHub. Le rang affiché sur la carte de statistiques est un percentile pondéré basé sur les distributions exponentielle et log-normale, avec des rangs de S à C, suivant le système de notation académique japonais. L'algorithme de statistiques linguistiques utilise la formule ranking_index = (byte_count ^ size_weight) * (repo_count ^ count_weight), avec des poids par défaut size_weight=1 et count_weight=0. Le README indique également qu'après une certaine pull request, l'instance publique devrait être capable de gérer plus de 5 000 requêtes par heure, mais il ne fournit pas de benchmark.

Déployer votre propre instance

Le README recommande l'auto-hébergement pour des cartes fiables. Deux approches sont documentées. La première utilise GitHub Actions pour générer des SVG statiques selon un calendrier et les committer dans votre dépôt de profil, en utilisant GITHUB_TOKEN pour les données publiques ou un PAT pour les statistiques privées. La seconde est l'auto-hébergement sur Vercel ou une autre plateforme, ce qui nécessite un PAT avec des portées spécifiques. Des variables d'environnement telles que CACHE_SECONDS, WHITELIST, GIST_WHITELIST, EXCLUDE_REPO et FETCH_MULTI_PAGE_STARS contrôlent le comportement. Par exemple, WHITELIST est une liste séparée par des virgules de noms d'utilisateurs GitHub autorisés à accéder à votre instance, et EXCLUDE_REPO exclut des dépôts des statistiques sans exposer les noms dans les URL. Le README avertit également que le support des plateformes non-Vercel est limité et que vous devez redéployer après avoir modifié les variables d'environnement.

État de maintenance et licence

Le haut du README contient un avis indiquant que le dépôt n'est plus maintenu. Il dirige les utilisateurs vers un projet successeur nommé GitHub Stats Extended, décrit comme un fork activement maintenu avec des fonctionnalités supplémentaires et une stabilité améliorée, ou vers GitHub Readme Stats Action. La documentation existante est conservée pour référence uniquement. Le projet est sous licence MIT, qui permet l'utilisation, la copie, la modification, la fusion, la publication, la distribution, la sous-licence et la vente de copies, à condition que l'avis de droit d'auteur soit inclus. La licence exclut également toute garantie et responsabilité. Le README ne mentionne aucune garantie de sécurité, engagement de support ou benchmark de performance, en dehors des valeurs par défaut du cache et de la note sur le traitement de plus de 5 000 requêtes par heure.

Test ciblé de github-readme-stats

GitHub Readme Stats génère des cartes SVG dynamiques destinées aux fichiers README. Les paramètres de requête déterminent la carte, le thème et les informations affichées. Cette architecture est pratique pour un profil GitHub, mais elle introduit une dépendance à un service ou à une instance auto-hébergée. Les thèmes intégrés et les options documentées doivent être testés avec le nom d'utilisateur réel, un dépôt privé éventuel et les limites d'API associées.

Pour une validation ciblée, copiez l'URL de carte indiquée par le README dans un README de test et inspectez le SVG retourné, son temps de réponse et le rendu en mode clair puis sombre. Vérifiez aussi le comportement d'un utilisateur sans activité et d'une API GitHub limitée. Le dépôt ne transforme pas ces cartes en métrique officielle de contribution : elles reflètent les données accessibles au générateur. La licence MIT facilite l'hébergement et l'adaptation, sous réserve de conserver les avis requis.

Conclusion éditoriale

github-readme-stats s'adresse aux équipes dont le besoin correspond exactement au périmètre décrit dans le README. Il ne faut pas le traiter comme une garantie de production : commencez par le scénario propre à anuraghazra/github-readme-stats, la commande ou le fichier documenté, puis observez la sortie, les erreurs, les permissions et les ressources consommées.

Sources officielles

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