Associer commits conventionnels et changelog pour gérer vos projets Git comme un pro

Lorsque l’on débute le développement logiciel ou développement web, l’utilisation de Git est un indispensable pour suivre l’avancement de ses side-project, projets d’études ou exercice pratique. Que l’on soit plutôt GitLab ou GitHub, l’utilisation de Git en milieu professionnel est indispensable et d’autant plus important que les commentaires peuvent être vues par de nombreuses personnes dont parfois le client. En effet suivant l’importance du projet, le client peut voir le commentaire rédigé dans un commit dans le commentaire de résolution de son ticket ou plus simplement dans le journal des changements ou changelog.

Cette article présente rapidement deux pratiques à intégrer pour utiliser Git de manière professionnel :

  • le commit conventionnel
  • le changelog (journal des changements)
Pexels @ThiIsEngineering

Qu'est-ce que Git ?

Git est un système de contrôle de version largement utilisé au sein des équipes de développement. Il est devenu la norme open source du contrôle de version dans le développement logiciel. Son succès font de lui qu’il est également utilisé dans d’autres domaines comme l’édition par exemple. Entièrement décentralisé, Git a été conçu pour répondre à 3 objectifs : performances, sécurité et flexibilité.

Chaque enregistrement validé crée une photo instantanée de l’ensemble des fichiers modifiés du projet qui est ensuite synchronisé avec la copie de référence sur un serveur distant.

Introduction aux commits conventionnels

Indispensable aux projets de long terme pour les personnes qui travaille sur le projet mais aussi tout personnes extérieurs s’intéressant à l’évolution du produit dans ses moindres détails. C’est aussi un excellent exercice pour se préparer la gestion du code de manière professionnel en respectant les principes directeurs les plus répandus.

Qu'est ce que le commit conventionnel ?

Il s’agit d’une convention légère de spécifications pour des messages propres, clairs et explicite pour toutes personnes professionnels du développement ou pas. Mais surtout bénéficier de l’ajout des messages dans le journal des modifications (changelog). Les messages commit  pourront alors être répertoriés dans les grandes thèmes que sont les fonctionnalités, les correctifs et les modifications importantes.

Qu'est-ce qu'un changelog ou journal des changements ?

Le changelog ou journal des modifications aussi appelé journal des changements est un document texte simple contenant une liste chronologique et exhaustive de tous les changements effectués dans chaque version.

Il permet à tous utilisateurs, chef de projet, développeurs, product owner… de savoir exactement le contenu de chaque version et améliorer le débogage et le contrôle des erreurs.

Pour en savoir plus, vous pouvez consulter l’article sur l’intérêt de créer un changelog dés vos premiers commit.

Principe de base du commit conventionnel

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Utilisé dans de nombreux projets, il autorise les variantes : VueJS, Angular

L’ensemble de la documentation est disponible sur ConventionalCommits.org.

Les principaux termes d'un commit conventionnel pour un changelog propre

type : Indique brièvement le type de changement réalisé. Celui-ci peut-être :

  • fix pour indiquer les bugs résolus (hors vulnérabilités) (à relier avec patch en cas de corrections de bugs majeurs)
  • add pour indiquer l’ajout de fonctionnalités (à relier avec un niveau d’importance minor ou major pour les changements de numéros de versions)
  • change pour les modifications opérées à une fonctionnalité (à relier avec un niveau d’importance minor ou major pour les changements de numéros de versions)
  • remove pour les fonctionnalités supprimées
  • sec pour les vulnérabilités corrigées

Il est possible d’utiliser d’autres types basés sur des types déjà utilisés ou crées lors d’un effort collectif de standardisation (build, chore, ci, docs, style, refactor, perf, test, seo)

[optional scope] : Facultatif, le champ portée est optionnel est un nom indiquant la portée du changement effectué. Il s’agit de nommer son changement.

<description> : Message court à l’impératif énumérant chaque modifications effectuées (ajouts, suppressions, corrections, vulnérabilités). Ne pas hésiter à reprendre la TO DO LIST cachée dans le code pour lister ces changements .

[optional body] : Facultatif, le corps de message est optionnel et libre. Il s’agit d’expliquer ce que vos changements apportent au projet et pourquoi ces modifications ont été réalisées.

Tous les commits n’ont pas forcément besoin d’un corps de message surtout pour les projets simple ou personnel sans impact utilisateur.

[optional footer] : Facultatif, le pied de page est optionnel et s’ajoute après une ligne vide. Celui-ci peut contenir des informations supplémentaires quant aux changements réalisés : numéro de ticket traités, méthode de développement, personnes associés…

Le pied de page optionnel permet aussi de préciser les changements de version en indiquant BREAKING CHANGE ou plus simplement en marquant ! après <type>[optional scope] !

Quels avantages à combiner ces pratiques ?

  • Générer un changelog clair avec possibilité de l’automatisé
  • Déterminer plus simplement les changements de versions
  • Structuration de l’historique chronologique des commits
  • Facilité la communication au sein de l’équipe, des parties prenantes et du public intéressé

Il y a un avant/après dans les projets mettant en place une gestion des commits conventionnels. C’est un changement qui peut faire des dégâts au sein des équipes rigides et personnes adeptes des projets à la va-vite ou appliquant la méthode la R.A.C.H.E 😅 😂 🤣.

Quels inconvénients à combiner commit conventionnel et changelog ?

  • Oblige le développeur ou les membres de l’équipe à respecter la structure établie
  • Lourd à mettre en place pour les petits projets
  • Nécessite un temps d’adaptation personnel et au sein d’une équipe (Quid des nouveaux arrivants)
  • Peut faire doublon avec le changelog générer par votre outil de gestion de projet comme Jira par exemple

Cette liste non exhaustive vous montre une chose. En réalité, il n’y a pas vraiment d’inconvénient à pratiquer les commits conventionnels. Sa mise en place peut paraître lourde quant à la sélection des bons termes qui seront employés par tous et nécessitera comme tout changement un temps d’adaptation. Mais cela permet tout de suite de distinguer un développeur professionnel de celui qui pousse à la va-vite.

Pré-requis pour utiliser les commits conventionnels et changelog dans vos projets

Pour bénéficier pleinement de tous les avantages des commits conventionnels, il nécessaire de :

  • Choisissez de rédiger vos messages en anglais ou en français [Attention ce débat peut être houleux alors retenez ceci : l’anglais c’est professionnel]
  • Adapter l’équipe et l’organisation aux principes de keepchangelog.com
  • Disposer d’un dépôt Git pour votre projet
  • Créer un fichier CHANGELOG.md avec git touch CHANGELOG.md
  • Rédiger vos commits avec des guillemets simples ou des guillemets doubles

git commit -m 'message avec retour à ligne en appuyant entrée'

ou

git commit -m « ligne 1 » -m « ligne 2 »

Quelques ressources pratique pour s’améliorer sur Git

« Pro Git » de Scott Chacon et Ben Straub édition Apress disponible gratuitement sur le site git-scm et sur amazon pour la version broché

« Git – Maîtrisez la gestion de vos versions » de Samuel Dauzon édition ENI disponible chez les bons libraires et sur Amazon

Formation Git de Grafikart disponible sur son site et Youtube (abonnez-vous à sa chaîne)

Playlist Youtube de GetCodingKnowledge pour apprendre Git

Allez plus loin

Il s’agit d’une présentation succincte des bénéfices liés à l’utilisation de commits conventionnels. A l’heure où vous allez lire cette article, il se peut qu’il existe d’autres outils et que les conventions aient évoluées.

De plus, certains outils de gestion de projet intègre cette fonctionnalité ce qui simplifie grandement la vie des équipes de développement, produit et projet. Ceci d’autant plus simple quand le dépôt est connecté à l’outil de gestion de projet.

Pour en savoir plus sur la rédaction de commit professionnel, les bénéfices et la gestion professionnel de vos changements grâce au changelog. Vous pouvez consulter l’article sur les bénéfices à utiliser un changelog dés le début de vos projets.

photo du profil de syl20pro

A propos de l'auteur

Je suis Sylvain Gemieux alias syl20pro, spécialiste en gestion, maintenance du patrimoine immobilier avec un goût prononcé pour l’informatique et la transformation numérique.

J’aime partager sur mon blog et mon site web mes découvertes, expériences pro et perso. Retrouvez-moi sur vos réseaux sociaux.

Laisser un commentaire

Votre adresse e-mail ne sera pas publiée.

Ce site utilise Akismet pour réduire les indésirables. En savoir plus sur comment les données de vos commentaires sont utilisées.