Ce que regarde l’analyse automatique

Documentation

Un README à la racine

C’est la première chose qu’on lit en arrivant sur le projet. Ce qui aide le plus :

• commencer par un titre (# Nom du projet), sans badge ni logo avant, suivi de deux ou trois phrases : à qui s’adresse le projet, à quoi il sert, et l’adresse du site s’il y en a un ;
• découper le texte en parties : par exemple Fonctionnalités, Utilisation, Installation (ou Mise en route), Contribuer, Licence ;
• expliquer comment s’en servir et comment l’installer ou le lancer, avec des phrases : une commande seule dans un bloc de code ne dit pas à un enseignant ce qu’il doit faire ;
• ajouter au moins une capture d’écran, avec un texte alternatif qui la décrit.

Le README proposé par GitLab à la création du projet (« Getting started », « Suggestions for a good README »…) n’est pas pris en compte : remplacez-le par votre propre texte. De même pour le README d’un modèle (site HTML, MkDocs, exemple de GitLab Pages…) recopié sans changement : le même texte se retrouve dans des dizaines de projets et ne dit rien du vôtre.

Une licence

Sans licence, personne n’a le droit de réutiliser, modifier ou partager le projet, même s’il est public. Placez le texte complet de la licence dans un fichier LICENSE (ou LICENCE, COPYING, avec ou sans .md ou .txt) à la racine du dépôt. Pour du code, les licences courantes sont MIT, GPL-3.0 ou EUPL-1.2 ; pour des contenus pédagogiques, CC BY ou CC BY-SA. La documentation de la forge aide à choisir.

Un guide de contribution et un journal des versions

• CONTRIBUTING.md, à la racine : comment signaler un problème, proposer une modification, tester.
• CHANGELOG.md, à la racine, ou des releases sur la forge : ce qui change d’une version à l’autre.

Présentation sur la forge

Ces réglages se trouvent dans Paramètres › Général du projet :

• une description d’une phrase au moins : elle apparaît dans les résultats de recherche ;
• des sujets (mots-clés) : discipline, niveau, type d’outil ;
• une image du projet (avatar) ;
• pour une application ou un site : une publication GitLab Pages visible par tout le monde (Paramètres › Général › Visibilité › Pages), dont l’adresse figure dans le README.

Être trouvé dans la recherche

Un enseignant tape quelques mots : « quiz », « chronomètre », « fractions cm2 »… Pour que votre projet sorte, et sorte bien placé :

• Dites ce que fait le projet avec les mots de vos collègues, dans le nom, la description et les sujets : « quiz » ou « QCM » plutôt que seulement « H5P » ou le nom d’une technique.
• Indiquez la discipline et le niveau en clair (« mathématiques », « cycle 3 », « collège »…) : ce sont ces mots qui permettent de deviner les étiquettes affichées sur la fiche et de filtrer avec discipline: ou niveau:.
• Tout le README compte, mais ce qui est répété ou placé au début compte davantage : un mot cité une fois au milieu d’une longue page aide peu.

À pertinence égale, les projets documentés, sous licence, avec un site en ligne, actifs et réutilisés passent devant. Répéter un mot partout ne sert à rien : sa présence dans plusieurs champs ne compte que pour un petit bonus.

Suivi du projet

Ces informations sont données pour mémoire, sans jugement : date du dernier commit, nombre de commits et de contributeurs, tickets ouverts et fermés, merge requests fusionnées, versions publiées (tags ou releases), présence d’une intégration continue (.gitlab-ci.yml) et état du dernier pipeline. Un petit projet stable n’a pas besoin d’être modifié souvent.

Ce qui n’est pas regardé

Le code lui-même, sa qualité, son accessibilité, ses dépendances et la présence éventuelle de mots de passe ou de clés dans le dépôt. Ces points comptent pourtant beaucoup : l’audit des Forgéales s’en charge.

Sécurité

Faire auditer son projet

L’audit des Forgéales analyse un dépôt de la forge : failles connues de ses dépendances, mots de passe ou clés oubliés dans le code, erreurs courantes, appels à des services extérieurs. Il compare les dépendances aux bases de failles telles qu’elles sont au moment de l’analyse : relancez-le après une vague d’alertes.

Il ne voit pas la version de PHP ou de Node.js qui fait tourner votre application sur un serveur. Quand une faille touche PHP ou Node.js eux-mêmes, mettez à jour le serveur, ainsi que les images citées dans vos fichiers .gitlab-ci.yml ou Dockerfile (image: node:…, FROM php:…).

Les bibliothèques copiées ou chargées depuis un CDN

Un site peut inclure directement jquery.min.js, une bibliothèque de graphiques ou de mathématiques, copiée dans le dépôt ou chargée depuis un CDN. L’analyse des dépendances ne voit pas toujours ces bibliothèques. Indiquez une version précise, mettez-la à jour quand une faille est annoncée, et, pour un CDN, ajoutez l’attribut integrity qui empêche le navigateur d’exécuter un fichier modifié.

Jamais de secret dans le dépôt

• Pas de mot de passe, de jeton ni de clé d’API dans le code ou la configuration publiés.
• Un site GitLab Pages n’a pas de partie cachée : une clé d’API Grist ou un mot de passe d’application Nextcloud placé dans son code est lisible par tous, et ouvre l’accès à tous vos documents. Pour afficher des données, partagez plutôt un document Grist en lecture seule, ou un lien de partage Nextcloud sans droit de modification.
• Une clé publiée par erreur doit être révoquée : supprimer le fichier ne suffit pas, elle reste dans l’historique.

Retirer un projet

Ajoutez au projet le sujet no-index (Paramètres › Général) : il disparaîtra de l’index, et de ses détails, à la prochaine mise à jour. Un projet supprimé ou rendu privé en disparaît aussi.