Cet article a été rédigé suite à la lecture de plusieurs articles et vidéos de Delicious Insights à propos des conventions et automatisations autour des commit, qui m'ont inspiré et donné envie de rafraîchir ce qui y est présenté (c'est fou comme tout évolue en 3 ans !).

Quelles conventions pour nos commit ?

Le but d'un commit, c'est de clarifier le travail réalisé dans le paquet de ligne qu'il regroupe. C'est comme un chapitre d'un guide de voyage, qui regroupe plusieurs pages. Plus il est clair, plus on sait où chercher pour trouver les infos qui nous intéressent.

commit : test
commit : retest
commit : ça marche !
commit : Debug router
commit : test à nouveau
...

Au fur et à mesure de son avancée, un certain nombre de concepts et de conventions s'imposent à tout développeur, qu'il soit consciencieux ou juste confronté au travail d'équipe... !

Pour uniformiser les bonnes volontés, deux conventions ont vu le jour : Les conventions de version sémantique (Semver) pour les montées de version, et les conventions de nommage des commit. Ces deux conventions proposent tout ce qu'on retrouve de manière très classique. Bien sûr si on est un outsider, on peut se retrouver à l'étroit, mais pour 99,99% des projets, cela sera parfaitement adapté.

Je ne vais pas m'étaler ici sur leur utilité, je pars du principe que c'est compris, sinon vous ne seriez pas là ! 😄

Comment se rappeler (ou automatiser) les nommages des commit

Quelle est la liste des mots que vous pouvez mettre au début ? feat, fix, docs, ... Ah vous ne vous souvenez pas des 8 autres ? Moi non plus. 😓

Et en même temps, pourquoi s'en rappeler, il y a des outils qui peuvent nous aider ? Il est bien plus sûr d'utiliser un assistant pour cela, que d'essayer de faire quelque chose d'à peu près ok, mais qui en fait ne rentre pas dans la convention, et qui n'est donc pas automatisable.

Il est possible :

• de mettre en place un assistant pour nous aider à rédiger nos commit
• de valider le noms de nos branches,
• de vérifier automatiquement un certains nombre de choses à chaque commit
• d'uniformiser par la même occasion le travail de toute l'équipe !

Dans l'idée, le format conventionnel se trouve être :

<type*>[scope optionnel]: <description*>

[body optionnel]

[notes/pied de message optionnels]

Vous aurez besoin d'installer Husky pour aller plus loin, je vous laisse suivre cette astuce si ce n'est pas déjà fait.

Aide à la rédaction des messages de commit

Nous y voilà ! Je ne vous fais pas attendre plus longtemps ! 😉

CommitLint

CommitLint permet de vérifier le format du texte du commit, pour s'assurer que ça répond bien à un standard. Il s'exécutera automatiquement à chaque commit.

Installation

npm install --save-dev @commitlint/cli @commitlint/config-conventional

Comme au-dessus, on l'installe en dépendance de développement uniquement. On installe deux dépendances, le cli, qui va nous permettre de faire des commandes, et la configuration conventionnelle.

Configuration de commitLint

On a ensuite besoin de paramétrer commitLint pour lui dire quel configuration il doit suivre. Nous venons d'installer config-conventional, il faut le lui préciser, dans un fichier commitlint.config.js :

module.exports = {
  extends: ['@commitlint/config-conventional'],
}

Il en existe pleins d'autres, que je vous laisse aller regarder dans le repo du projet.

On peut même aller plus loin dans la configuration en traduisant les phrases de l'outil en français, pour mieux comprendre ce qu'on fait ! C'est quand même fabuleux !

module.exports = {
  extends: ['@commitlint/config-conventional'],

  prompt: {
    messages: {
      skip: ':skip',
      max: 'pas plus de %d caractères',
      min: 'au moins %d caractères',
      emptyWarning: 'ne peut être vide',
      upperLimitWarning: 'au-dessus de la limite',
      lowerLimitWarning: 'sous la limite'
    },
    questions: {
      type: {
        description: "Choisissez le type de modification concerné par votre commit :",
        enum: {
          feat: {
            description: 'Ajout/mise à jour de fonctionnalité',
            title: 'Features',
            emoji: '✨',
          },
          fix: {
            description: 'Correction de bug',
            title: 'Bug Fixes',
            emoji: '🐛',
          },
          docs: {
            description: 'Ajout/modif de documentation',
            title: 'Documentation',
            emoji: '📚',
          },
          style: {
            description: 'Modif de style et de mise en forme du code (espacements, virgules, etc.)',
            title: 'Styles',
            emoji: '💎',
          },
          refactor: {
            description: 'Modif des sources n’étant ni un correctif, ni un ajout de fonctionnalité',
            title: 'Code Refactoring',
            emoji: '📦',
          },
          perf: {
            description: 'Amélioration de la performance',
            title: 'Performance Improvements',
            emoji: '🚀',
          },
          test: {
            description: 'Ajout ou correction de tests',
            title: 'Tests',
            emoji: '🧪',
          },
          build: {
            description: 'Modif. affectant le "build" ou les dépendances externes (exemples de contextes :  webpack, broccoli, npm)',
            title: 'Builds',
            emoji: '🛠️',
          },
          ci: {
            description: 'Modif. de la configuration ou des scripts liés à la CI (.gitlab-ci.yml, grumphp, docker, etc.)',
            title: 'Continuous Integrations',
            emoji: '⚙️',
          },
          chore: {
            description: "Autres mises à jour ne modifiant ni les sources, ni les tests",
            title: 'Chores',
            emoji: '♻️',
          },
          revert: {
            description: 'Annuler (revert) un commit précédent',
            title: 'Revert',
            emoji: '🗑️',
          },
        },
      },
      scope: {
        description:
          'Quel est le contexte des modifications (composant, nom de fichier)',
      },
      subject: {
        description: 'Écrivez une description concise, à l’impératif',
      },
      body: {
        description: 'Renseignez une description plus détaillée des modifications',
      },
      isBreaking: {
        description: 'Y a-il des changements majeurs ("breaking changes") ?',
      },
      breakingBody: {
        description:
          'Un commit cassant la compatibilité ascendante ("breaking changes") nécessite un corps de message. Veuillez renseigner une description plus longue et détaillée que la première ligne du commit.',
      },
      breaking: {
        description: 'Décrivez les "breaking changes"',
      },
      isIssueAffected: {
        description: 'Cela concerne-t-il un ticket existant ?',
      },
      issuesBody: {
        description:
          'Vous devez ajouter un corps au message si ce commit ferme des tickets. Essayez de renseigner une description plus longue et détaillée que la première ligne du commit.',
      },
      issues: {
        description: 'Ajoutez une référence de ticket ("fix #123", "ref #123")',
      },
    },
  }
}

Retrouvez ici la documentation de commitLint.

Configuration de Husky

Afin d'automatiser le processus, on va demander à Husky d'écouter la création du message, en créant un nouveau fichier commit-msg, dans lequel on mettra :

# Contenu du fichier commit-msg
npx --no-install commitlint --edit $1

C'est super, parce que ça empêche des commit mal formatés de passer. Mais... Comment bien les formater du coup ? Parce que nous avons commencé cet article en se disant que c'était compliqué de se souvenir de tout... C'est là qu'intervient Commitizen.

Commitizen

Commitizen sert à nous aider à rédiger les commit. Il peut s'installer localement, dans un projet, ou bien globalement sur toute la machine, pour servir partout. Nous allons voir les deux.

Installation

# Pour une installation locale :
npm install --save-dev @commitlint/cz-commitlint commitizen

# Pour une installation globale :
npm install --global @commitlint/cz-commitlint commitizen

L'avantage de l'installation globale est qu'elle nous permet de d'utiliser cet outil pour tous nos projets, et donc de mieux intégrer ces démarches dans notre quotidien de dev. Le défaut, c'est que si ça ne fait plus partie du projet, un dev qui ne l'aurait pas installé globalement se retrouverait à ne plus avoir du tout commitizen d'installé. Je conseille de faire les deux.

Pour pouvoir exécuter commitizen, on doit ensuite taper la commande suivante :

npx cz

Elle n'est pas bien longue, mais très éloignée de l'univers git... Perso ça me déstabilise de faire un truc qui n'a rien à voir avec git, pour faire un commit.

Configuration

Je préfère donc créer un alias, pour avoir une commande git qui embarque cette commande-là :

# Pour une installation locale :
git config --local alias.cz "npx cz"

# Pour une installation globale :
git config --global alias.cz "npx cz"

De cette manière je peux maintenant faire :

git cz

Et automatiquement, ça ouvre commitizen pour m'aider à rédiger mes commit. Super pratique !

Bon dev !