Les README.md sont des fichiers qui servent principalement à expliquer comment un développeur peut exécuter une application et sa suite de tests. Aujourd’hui j’aimerais qu’on se penche sur ce qu’est un bon README.md et quels sont les pièges à éviter.

Note : Je parle ici dans un contexte professionnel en entreprise. Les fichiers markdown pour les projets open source doivent contenir de l’information différente qui n’est pas traitée ici.

Une entête basique qui décrit le projet

Bon. Je commence soft. Évidemment, vous allez mettre le titre du projet avec une description brève de sa mission au sein de l’entreprise. L’important, c’est de ne pas de surdocumenter. De l’information qui risque de changer, comme des règles fonctionnelles ou des diagrammes d’architecture, n’a pas sa place ici.

Voici un exemple :

Résumez en un paragraphe.

Les prérequis

Ici, vous allez lister les dépendances du projet. On peut penser à des librairies ou des pilotes (drivers) par exemple.

D’abord, réservez une section pour lister ces dépendances. Puis, à la suite, dans le même ordre, ajoutez les procédures d’installation. Sans nécessairement entrer dans les détails, simplement écrire sous forme de liste à puces comment l’installer, comme par exemple :

Comment exécuter et ouvrir l’application

En théorie, le développeur qui essaie de monter son environnement à partir de notre README.md devrait avoir une copie du code sur son poste et toutes les dépendances installées. Ici, on veut qu’il puisse démarrer l’application et tester que tout est ok.

C’est aussi dans cette section que vous voulez indiquer au développeur s’il doit modifier des variables d’environnement, des fichiers de configuration, des clés d’API privées, etc.. Voici un exemple :

Comment exécuter les tests

J’ose espérer que votre branche master est propre et que tous les tests roulent 😛 Donc, une fois que l’environnement est prêt pour développer, le programmeur doit savoir comment exécuter les tests pour valider que ses changements ne causent aucune régression.

Si vous avez plusieurs niveaux de tests (unitaires, fonctionnels, bout-en-bout ou e2e, etc.), vous devez y allez dans l’ordre logique et cet ordre dépend du contexte de votre projet. Dans mon exemple, on pourrait vouloir expliquer comment exécuter les tests unitaires en premier, puis les tests bout-bout, comme par exemple :

Bien sûr, tout dépendant de votre projet, les procédures peuvent être plus compliquées 😛

Comment déployer/graduer

Toujours dans l’optique de rendre un développeur autonome rapidement, une section contenant une procédure pour déployer son code dans un environnement de tests peut être très pratique, quoique je la considère optionnelle :

Dans le cas où une branche serait connectée à un pipeline de déploiement en continu, il peut être pratique de le mentionner au lieu d’inscrire une procédure :

Conclusion

Aujourd’hui, on a vu ce que devrait contenir un bon README.md dans un projet. Gardez en tête que, peu importe son niveau, un développeur devrait être en mesure de cloner votre dépôt, lire le README.md et être prêt à coder. Si vous trouvez que cet article est intéressant, n’hésitez pas à le partager avec vos collègues. Je ne pense pas détenir la vérité absolue, mais si cet article peut être un point de départ pour une discussion entre collègue et arriver avec vos propres README.md encore mieux, ce sera mission accomplie!

Cheers!