D’accord, maintenir un journal de modifications pour chaque projet est un peu rébarbatif, mais si vous le faites, votre moi du future va adorer votre moi du passé.
Changelog : de quoi parle-t-on ?
Le plus souvent, un journal de modifications prendra la forme d’un fichier texte, au format markdown, nommé CHANGELOG.md.
On y trouvera pour chaque version, la liste des évolutions notables.
Un journal de modifications, c’est utile
On ne sais jamais à l’avance combien de temps va durer un projet (surtout un projet web). Donc, dans le doute, il vaut mieux se dire que ça peut durer suffisamment longtemps pour oublier quand est intervenu telle modification, et surtout pourquoi.
Par exemple, si on m’avait dit que l’extension sur mesure utilisée pour gérer les formations en ligne (e-learning) du site Rhumato DPC aller évoluer pendant plus de 10 ans, je ne l’aurais pas cru. En effet, le projet a commencé en 2013. Autant vous dire qu’à cette époque là, je n’avais pas la rigueur que NOUS nous imposons actuellement.
J’ai donc commencé la tenue du journal de modifications après la première mise à jour en production, en 2015. Heureusement j’ai pu assez facilement récupérer l’historique des modifications grâce au versionnage des fichiers. Depuis, le CHANGELOG.md est maintenu régulièrement.
Et heureusement ! Car tout au long du projet, et au gré des changements d’interlocuteurs, nous avons souvent (deux fois par an en moyenne) besoin de retrouver pourquoi tel ou tel comportement se produit.
Est-ce un bug, un effet de bord ? Non ! C’est une demande d’il y a 4 ans pour un cas de figure spécifique !
Lorsque l’on retrouve la version et la date de déploiement de la fonctionnalité : effet pro garanti ! Mais surtout, cela aide à contextualiser le nouveau besoin. C’est ici que vous remerciez votre moi d’il y a 4 ans , d’avoir tenu un journal de bord.
Un journal de modifications, c’est contraignant
C’est contraignant, car cela nécessite de la discipline, mais pas que :
- D’abord, cela rajoute une étape à chaque évolution : faire l’évolution ET la répertorier.
- Ensuite cela implique de versionner le projet. Oui oui, avec des numéros comme : v2.5.0
Une contrainte en plus, représente donc du travail en plus, alors est-ce vraiment intéressant ?
La réponse est oui !
Car formaliser les évolutions et les rassembler par paquet (version) va de fait structurer votre travail et le faire monter en qualité.
- Répertorier les changements, c’est faciliter la une enquête dans le futur (on l’a déjà dit)
- Mettre des mots sur une évolution, c’est mieux la comprendre
- Rassembler les fonctionnalités, c’est assurer la cohérence entre elles
- Pointer les versions stables, c’est la possibilité de rétrograder facilement
- Chaque note de version est l’occasion de communiquer sur les nouveautés auprès de ses clients, collaborateurs ou de sa communauté.
Un journal de modifications, c’est facile
Heureusement, avec un peu de méthode, la contrainte va peu à peu s’effacer au profit des avantages.
Identifier les nouveautés, vous le faites déjà
En tout cas, vous devriez, si vous utilisez un outil de versionnage comme git.
En effet, chaque commit est censé faire l’objet d’un commentaire explicite. Ainsi, si vous évitez les « commit », « debug », « wip » un simple copié / collé des derniers commits constituera une bonne base à la prochaine note de version.
Cela demande simplement de s’attarder un tout petit peu sur le travail que l’on vient d’effectuer. En passant, devoir verbaliser une modification entraîne souvent un travail plus réfléchi et donc de meilleure qualité.
Éditorialiser les nouveautés, vous le faites déjà
En tout cas, vous devriez, pour annoncer les changements.
S’il s’agit d’un projet public, de type logiciel, module, extension ou thème, la pratique est quasiment obligatoire.
Si le projet est celui d’un client, communiquer les évolutions et changements importants, ne serait-ce que par mail ou messagerie instantanée est la moindre des choses. Dans ce cas, votre note de version est déjà toute prête.
Conclusion
Même pour un projet purement interne, ne vous laissez pas aller à la facilité. Maintenez un changelog : vos collègues ou votre moi futur vous remercieront.
