Commitizen – passer aux Conventional Commits en douceur

Je vous le dis : vous allez devenir un·e véritable maître·sse du commit. Déjà parce que vous avez pris connaissance de cette convention grâce à cet article. Ensuite, parce que vous avez découvert des exemples plus pratiques afin d’adopter de nouvelles habitudes grâce à cet autre article. Aujourd’hui, je vous présente Commitizen, un petit assistant en console bien pratique qui vous aidera à appliquer les concepts des Conventional Commits. Avant de vous expliquer comment l’installer, je vous propose de vous montrer comment il fonctionne.

Comment marche Commitizen ?

Pré-requis d’utilisation

Commitizen permet de créer un commit appliquant les Conventional Commits. Il faut donc se placer dans un projet versionné avec Git et ouvrir un terminal pour Linux, ou un PowerShell pour Windows. Pour écrire un commit et l’envoyer sur le serveur de version, il faut avoir modifié des fichiers. Ensuite, il suffit de taper la commande suivante :

git cz

C’est beaucoup plus court que git commit 😀. Après avoir tapé la touche Entrée, un assistant se lance.

L’assistant git cz

L’assistant vous demande de préciser le type de votre commit : avez-vous développé une nouvelle fonctionnalité, réparé un bug… ? Servez-vous des flèches de votre clavier pour choisir le type, et appuyez sur la touche Entrée pour valider.

Vous pouvez aussi saisir le scope (la portée) de votre modification / création. C’est facultatif : appuyez sur la touche Entrée sans rien noter, si vous préférez.

La troisième étape correspond à la saisie du message du commit. Celui-ci doit être court mais compréhensible. L’outil Commitizen calcule automatiquement le nombre de caractères disponibles pour rédiger ce fameux message.

Ensuite, Commitizen vous demande si votre code implique des ‘Breaking changes’, c’est à dire des modifications que les utilisateurs finaux doivent prendre en compte. Par exemple : pour se connecter à l’API, l’identifiant / mot de passe ne fonctionnent plus et il faut se connecter directement avec un token.

Si vous répondez oui à cette question, le programme vous invite à compléter la partie description du commit.

Pour finir, Commitizen vous demande si votre code affecte un ticket déjà ouvert. Si vous répondez oui, vous pourrez renseigner le ou les tickets concernés. Il est très utile et même recommandé de relier du code à un ticket de bug / nouvelle fonctionnalité.

Après avoir recueilli toutes ces informations, Commitizen crée un commit.

Il ne vous reste plus qu’à faire un :

git push

Résultat dans GitHub d’un commit réalisé avec Commitizen

D’un coup d’œil, on constate qu’il s’agit d’un bug fix (réparation d’un bug) sur la partie HTML. Grâce au message, on sait que c’est une modification de l’en-tête HTML. Et pour finir, on trouve une description plus détaillée concernant ce qui a été fait.

Installation

Pré-requis d’installation

Le module de Commitizen fonctionne avec NodeJs et NPM. L’installation se passe par ici.

Installation de Commitizen

Il suffit d’ouvrir un terminal ou une console PowerShell et de taper la ligne suivante :

 npm install -g commitizen

Après l’installation, vous devez vous rendre dans un projet versionné avec Git. Si vous n’avez pas de fichier package.json dans votre projet, vous devez le créer à la racine.

Ensuite, éditez le fichier et placez-y les deux caractères ci-dessous :

{}

Enregistrez le fichier package.json. A présent, il faut initialiser votre projet selon les préceptes des Conventional Commits. Pour cela, tapez la commande suivante :

commitizen init cz-conventional-changelog --save-dev --save-exact

A la fin du processus, votre projet devient compatible avec les Conventional Commits. Il ne vous reste plus qu’à utiliser la commande « git cz » à la place de « git commit ».

Problème d’installation avec Windows

En fonction des installations, il arrive que Windows se montre réticent vis à vis de Commitizen. L’erreur générée est la suivante :

Pour faire simple, Windows ne vous donne pas l’autorisation de lancer le programme commitizen.psl. Pour parer à cette restriction, saisissez la commande suivante :

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Unrestricted

Windows vous met alors en garde et vous demande une confirmation supplémentaire. Validez l’opération avec la touche Y ou O en fonction de la langue de votre ordinateur.

Git exited with error code 1

En effectuant quelques tests avec Commitizen, je me suis heurté à une erreur sous Windows assez peu parlante de la part de Git. J’ai résolu le problème en effectuant un push sur des commits qui étaient en attente d’envoi sur le serveur de version. Pour éviter de vous retaper l’assistant, lancez la commande suivante :

git cz --retry

Je suis tombé sur une nouvelle erreur mais je n’ai pas trouvé de solution élégante. Donc à défaut, en cas de blocage, je vous présente ma solution imparable.

Tout d’abord, vous devez vous rendre dans le répertoire .git de votre projet courant.

Ouvrez le fichier COMMIT_EDITMSG avec votre éditeur favori.

Ce fichier contient le texte préparé par Commitizen pour le commit. Je vous invite à le sélectionner et à le copier-coller dans un autre fichier ou un bloc-note.

Ensuite, effectuez un commit manuel très simple, par exemple :

git commit -am "test"

A ce moment Git est prêt à envoyer votre code, mais le message n’est pas le bon. Pour insérer le message préparé par notre cher Commitizen, vous devez lancer la commande suivante :

git commit --amend

Un éditeur de texte s’ouvre : vous devez donc remplacer le message créé précédemment dans mon exemple « test » par le message conçu par Commitizen.

Enregistrez la modification, puis vous n’avez plus qu’à faire un :

git push

Le badge de Commitizen

Pour indiquer que votre projet suit cette convention, il est vivement recommandé d’ajouter un badge à votre fichier README.md. Voici le code à y apposer :

[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)

Conclusion

J’espère que désormais, vous êtes mieux équipé·e pour créer des projets avec une qualité optimale. Vous pourrez générer des Changelogs impeccables qui vous feront gagner beaucoup de temps sur les migrations, la transmission d’informations…

Alors, allez-vous enfin sauter le pas et intégrer la convention à vos prochains projets ?

Si vous avez des idées d’améliorations pour Commitizen, c’est un projet Open Source : vous pouvez donc y contribuer.