Comment écrire de bons changelog et readme ?

Ils sont présents dans la majorité des projets en développement web : le changelog et le readme sont là pour guider et informer les utilisateurs. Mais savez-vous comment bien les rédiger ? Vu toutes les informations qu’ils offrent, mieux vaut réussir à les rendre compréhensibles et accessibles au plus grand nombre ! Voici quelques conseils pour vous aider à écrire de bons changelog et readme.

Qu’est-ce qu’un changelog ?

Que ce soit sous la forme d’un fichier ou d’une simple liste présentée sur le site web d’un projet, le changelog désigne toutes les modifications apportées par les mises à jour d’un logiciel, d’un programme ou d’une application. Cette liste est à la fois essentielle pour les développeurs, les contributeurs mais aussi les utilisateurs à la recherche d’informations précises, ou qui souhaitent simplement suivre l’évolution du projet et en comprendre toutes les nouvelles fonctionnalités. 

En règle générale, tous les changelogs incluent à chaque mise à jour : 

• la version du projet auxquelles les modifications se rapportent ;
• la date à laquelle la nouvelle version mentionnée a été publiée ;
• les nouvelles fonctionnalités avec une description synthétique de ce qu’elles apportent ;
• les améliorations apportées aux fonctionnalités précédentes ;
• les corrections de bugs ; 
• les autres modifications majeures, comme un changement de compatibilité en raison de la nouvelle version ;
• les crédits pour mentionner toutes les personnes ayant contribué à ces modifications.

Il n’y a pas réellement de standard ni de mise en forme imposée pour construire son changelog. Cependant, quelques styleguides existent pour aiguiller les développeurs dans sa rédaction. Par exemple, chez BASH/, notre équipe de développement web utilise Common Changelog pour générer un fichier CHANGELOG.md (qui utilise donc le Markdown) tout en s’appuyant sur Git, un outil très important pour conserver chaque étape d’un projet web. 

Qu’est-ce qu’un fichier readme ?

Tout comme le changelog, le fichier readme (souvent nommé README.md) a pour objectif d’apporter des informations à des humains, qu’ils soient les développeurs, contributeurs ou utilisateurs du projet. Cependant, son objectif n’est pas tout à fait le même, puisqu’il sert ici plutôt de documentation de base pour comprendre le projet et l’utiliser rapidement. Il réunit ainsi toutes les étapes essentielles afin de savoir comment bien l’installer et le prendre en main.

En plus de toutes les indications importantes pour se servir du projet, quelques directives sont souvent données à ceux qui souhaitent y contribuer (règles de codage, tests…). Enfin, des informations sur la licence du projet sont également affichées, suivies des crédits incluant tous ceux qui ont participé au projet et les ressources utilisées.

Là encore, il n’y a pas de standard à suivre pour bien l’écrire. Certains développeurs décident alors de n’y intégrer que quelques bribes d’informations sur l’installation du projet, ce qui le rend finalement peu consulté.

Pourquoi le changelog et le readme sont-ils si importants ?

Avec leur manque de standardisation, le changelog et le readme se retrouvent dans une étrange position. À la fois pratiques et pensés pour clarifier un projet, ils finissent souvent par être négligés, pauvrement enrichis voire complètement abandonnés par leurs développeurs. Après tout, cette documentation n’est pas obligatoire. Pourtant, il y a de nombreux avantages à les intégrer dans tous vos projets !

D’une part, le changelog est plus souvent convoité par les personnes qui connaissent déjà votre projet. Côté dev, il est utile pour garder une trace concrète de vos avancées. Il s’avère donc très pratique pour repérer toutes les modifications à faire, que ce soit au niveau des bugs ou des améliorations. Côté utilisateur, il leur permet d’être tenu au courant des derniers changements apportés sur un logiciel dont ils se servent. Et ça, surtout s’ils l’utilisent souvent, c’est loin d’être négligeable ! Il s’agit aussi d’une documentation utile pour vous apporter un feedback vis-à-vis des nouvelles versions de votre projet.

D’autre part, le fichier readme est le premier élément que tout le monde remarque en arrivant sur un repository GitHub. Une mauvaise écriture de ce dernier risque donc de donner une mauvaise image de votre travail, surtout si votre projet est assez complexe à prendre en main. Un manque de clarté peut aussi rebuter les plus méfiants, qui craignent de mettre en danger leur appareil en installant un logiciel ou une application dont ils ne connaissent pas les fonctionnalités exactes.

Comment écrire un bon changelog ?

Sans standard précis, rédiger un bon changelog n’est jamais simple pour les développeurs ! Bien que des aides comme Common Changelog existent, nous avons réuni quelques informations complémentaires pour vous guider dans ce process.

Toujours suivre le même format

Pour que tout le monde comprenne votre changelog, utiliser des formats précis (et universels de préférence) est très important. Par exemple, nous vous conseillons d’écrire toutes vos dates au format YYYY-MM-DD. Pourquoi ? Déjà car ce format suit la norme ISO 8601, ensuite car cela évite les confusions d’un pays à l’autre. Le 06/01/2024 peut être lu « 1er juin 2024 » ou « 6 janvier 2024 ». Au contraire, écrire 2024/06/01 indique clairement une logique décroissante dans sa lecture : il s’agit donc du « 1er juin 2024 ».

Une fois qu’un ou plusieurs formats ont été adoptés, tâchez de les suivre à chaque mise à jour du changelog par souci de cohérence. 

Ne pas oublier le moindre détail

Dans un changelog, la moindre petite modification apportée au code a son importance ! Même s’il ne s’agit que d’un texte ayant changé de couleur, ce détail n’est certainement pas anodin. Il peut par exemple refléter un souci d’accessibilité web ou un léger changement dans la charte graphique. Pensez donc toujours à renseigner et regrouper chaque information, aussi infime soit-elle, selon sa date et sa nature (amélioration, bug, nouveauté…).

Rester clair, concis et structuré

Tout au long du changelog, vous devez vous tenir à une structure bien établie. Chaque nouvelle version doit avoir sa propre section, avec son nom et sa date placés en entête. Ensuite, toutes les catégories impliquées dans vos modifications (nouvelles fonctionnalités, corrections de bugs, retraits de fonctionnalités…) doivent être mises en avant de façon distincte, pour ensuite y lister tous les changements associés.

Dans le cas où vous avez créé un fichier CHANGELOG.md, voici un exemple de format à suivre pour y ajouter une nouvelle version : 

## VERSION - DATE

### Added
Liste de toutes les fonctionnalités ajoutées dans cette version

### Changed
Liste de toutes les modifications apportées dans cette version aux fonctionnalités existantes

### Fixed
Liste de tous les bugs ayant été corrigés dans cette version

### Removed
Liste de toutes les fonctionnalités retirées dans cette version

À noter : par souci de clarté, introduisez chaque élément de vos listes en utilisant l’impératif présent. Fix, Add, Document, Improve… Il n’y a pas de limite concrète aux verbes que vous pouvez utiliser ! Ainsi, « Missing logo has been fixed » doit plutôt s’écrire « Fix missing logo ». 

Ajouter des sources externes

Un bon changelog doit être bref et simple à comprendre, mais aussi suffisamment exhaustif ! Pour compléter les informations données, n’hésitez pas à ajouter des sources et des liens externes. Certaines modifications apportées en ont certainement besoin, pour être mieux comprises et appréhendées par les lecteurs du document.

Correctement mettre à jour le changelog à chaque nouvelle version

Une nouvelle version de votre projet vient de sortir ? C’est le moment de modifier votre changelog pour y ajouter ses nouveautés ! Placez toujours la version la plus récente en tête de liste, puis aidez-vous des informations données par Git pour structurer votre changelog. Surtout, ne vous fiez pas uniquement à l’automatisation proposée par l’IA : prenez bien le temps d’examiner chaque élément ajouté pour vous assurer que tout soit correctement retranscrit.

Donner des instructions précises pour bien effectuer les updates

Si le changelog doit détailler chaque mise à jour et ses fonctionnalités, c’est encore mieux s’il peut expliquer comment correctement l’effectuer ! Pour toutes vos versions les plus conséquentes, n’hésitez donc pas à retranscrire toutes les étapes nécessaires pour faire la mise à jour de votre projet et ainsi limiter le risque d’erreurs. C’est aussi une aide précieuse en tant que développeur pour ne pas perdre le fil des modifications et de ce qu’elles impliquent à chaque mise à jour.

Comment bien rédiger son fichier readme ?

Écrire un bon fichier readme ne s’improvise pas. Pour correctement intégrer toutes les informations essentielles qu’il requiert, voici quelques conseils à suivre quelle que soit la nature de votre projet.

Écrire une introduction simple mais descriptive du projet

En quoi consiste votre projet ? Quel est son objectif ? Pourquoi l’utiliser ? Le fichier readme doit indiquer toutes les réponses à ces questions de façon synthétique. Juste après son nom, écrivez un petit paragraphe résumant tout ce que les autres développeurs (mais aussi les utilisateurs qui n’y connaissent peut-être rien en codage) doivent savoir pour mieux comprendre l’objectif de votre projet.

Placer des badges

Les badges sont de bons indicateurs visuels pour comprendre au premier coup d’œil l’état de votre projet. Ils peuvent par exemple afficher l’état des tests, les versions disponibles, le nombre d’étoiles sur tel site, le nombre de téléchargements, les langues supportées… Bref, cette touche de dynamisme est à la fois pratique, facile à mettre en place et très user-friendly ! 

Structurer correctement chaque étape

Pour être correctement compris par tout le monde, vous voulez que votre README.md soit bien structuré de A à Z. Indiquez clairement (via des Hn) chaque catégorie, de l’installation à l’utilisation, en passant par les principales fonctionnalités du projet, des exemples de code et des instructions à donner aux potentiels contributeurs. Plus votre structure est claire, plus votre fichier sera lu, compris et rassurant pour vos utilisateurs. Il peut ainsi suivre le modèle suivant : 

# Nom du projet
Placer les badges souhaités
## Description
## Installation
### Prérequis
### Étapes
## Utilisation
## Fonctionnalités
## Exemples de code
## Contribuer
## Licence
## Crédits

Illustrer les instructions données

Pour étayer les étapes données aux utilisateurs (par exemple au moment de l’installation), n’hésitez pas à ajouter des captures d’écran ou des GIFs pour mieux les guider, surtout pour les manipulations les plus complexes. Si votre projet cible des néophytes complets en codage ou autre opération informatique, il s’agit d’une excellente solution pour qu’ils se sentent moins perdus !

Tenir à jour le fichier readme

Même si les mises à jour sont moins fréquentes qu’un changelog, un fichier readme est loin d’être figé dans le marbre à la sortie d’un projet. Certaines versions vont sûrement apporter des modifications majeures, que ce soit au niveau des fonctionnalités principales ou des façons de l’installer. Dans ce cas, n’oubliez pas de faire une repasse afin d’actualiser toutes les informations essentielles.

Vous souhaitez bénéficier d’un accompagnement technique complet sur votre projet web ? N’hésitez pas à faire appel à BASH/ ! Du site vitrine au site e-commerce, notre agence web lilloise se tient à votre disposition pour vous offrir une expertise qualifiée, réactive et flexible. Contactez-nous dès maintenant et prenons rendez-vous !