Arrêtez de massacrer vos messages de commits

Ok, mais c’est quoi le problème ?

La clareté d’un historique joue un rôle décisif pour la collaboration d’une part, mais également pour comprendre les évolutions du projet. Tu dois te considérer comme ton premier relecteur. Par exemple, après avoir créé certains commits le vendredi soir, si tu reviens le lundi et que tu n’as qu’à lire les derniers messages de commits pour te resituer et reprendre rapidement ton travail, tu y gagnes !

Les exemples cités juste avant tout comme ceux que j’ai rencontré sur mes projets ou ceux de mes clients me posent différents problèmes :

• on ne sait pas de quoi traite le commit ;
• on ne peut pas faire le lien avec un éventuel outil de gestion de projet (tâches / tickets / issues) ;
• on doit regarder dans le commit pour analyser ce qu’il contient et essayer de deviner ce qu’il traite ;
• il y a un risque que ces commits ne soient pas atomiques et aient d’autre incidences.

La critique est facile, mais que peut-on y faire ?

En gestion de projet, on définit au moins dans les grandes lignes les tâches à réaliser. On est donc, en théorie, capable de donner un cadre normatif à la rédaction des messages.

L’exemple classique que j’aime donner ici, c’est le fait de lier un commit à une tâche définie au préalable dans un outil de gestion de projet. Si en plus de ça tu utilises les outils de définition des tâches intégrés (les issues) à des solutions comme GitLab, GitHub, BitBucket (pour ne citer qu’eux), tu bénéficies d’emblée d’un avantage supplémentaire à cette démarche : la référence au ticket depuis le message sera automatiquement interprétée et liée au ticket après le partage (push). Et si on pousse encore plus loin, en utilisant des mots clés adaptés dans le message de commit, le ticket peut être automatiquement fermé. En gros, si on est appliqué, on peut gagner en temps, donc en efficacité, et en confort.

Ça à l’air sympa de définir une norme, mais n’y a-t-il pas déjà un modèle un peu standard ?

Tout à fait ! Des gens sympas, reproduisant des conventions assez similaires dans leurs entreprises, se sont dit que ça serait bien de fournir une base documentaire à cet effet. Ils ont appelé ça simplement “Les commits conventionnels”. Bon, en français, ça claque moins qu’en anglais : conventionalcommits.org.

Ils proposent un gabarit avec des éléments optionnels :

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Pour les types, ils ont repris ce qui avait déjà été étudié et proposé par des gens de Google pour Angular : feat, fix, build, chore, ci, docs, style, refactor, perf, test… Les deux premiers sont les plus utilisés :

• feat (pour feature) désigne l’ajout ou la participation à une fonctionnalité
• fix désigne un correctif

Bien évidemment, tu n’es pas contraint·e d’utiliser cette convention. Il existe de nombreuses autres manières de faire, certaines étant même documentées par et pour les outils de gestion de projet qu’elles doivent servir (le “JIRA smarts commit” en est un exemple connu).

L’idée reste la même : obtenir un historique qui ait de la valeur, autant pour les personnes qui reliront ou chercheront dans cet historique que pour fournir un contexte propice à d’autres facilités. C’est d’ailleurs le cas avec le conventionnal commit qui ouvre la porte à l’automatisation de la génération de numéros de versions logiciels (utilisant les tags) selon une autre norme, le Semanting Versioning, ou encore la génération automatique de changelog (une documentation decrivant les évolutions apportées dans le logiciel d’une version à une autre). L’outil que j’utilise pour ça s’appelle Semantic Release.

Alors, convaincu·e ?

J’espère que ces quelques arguments auront sû te convaincre de prendre soin de tes messages et de ton historique. Tu te demandes alors peut-être comment généraliser cette pratique dans ton équipe, ou comment faciliter son adoption (sans oublier le vocabulaire à employer) ? Et bien c’est tout simple, il suffit de trouver les outils qui pourront se greffer à Git et t’assister ou, à défaut, te rattraper en cas d’erreur. Parmi les nombreux outils qui existent, je te recommande de jeter un œil à commitlint et commitizen. Tu trouveras plus d’informations dans cet autre article.

Tu as maintenant dans les mains tous les savoirs pour améliorer la qualités de tes messages de commits. Si toutefois tu peines ou préfères être assisté·e dans tes démarches, n’hésites pas à me contacter.