Comment bien écrire ses commit avec Git
Dans l'image ci-dessus, nous voyons à quel point un commit mal commenté peut être nuisible, puisque nous ne comprenons pas la nature du changement survenu et son contexte. À long terme, l'effet est encore plus dommageable, car la maintenabilité du logiciel souffre des incohérences dans la portée de ces changements, et de la façon dont ils ont affecté le projet dans le passé.
En gardant cela à l'esprit, parlons un peu du modèle des Commits conventionnels.
Conventional commit qu'est-ce que c'est ?
Conventional Commits est une convention simple pour les messages de commit, qui suit un ensemble de règles et aide les projets à avoir un historique de commit explicite et bien structuré.
Comment l'utiliser ?
Les règles sont très simples, comme indiqué ci-dessous, nous avons un type de commit, le contexte (scope) du commit et le message (subject ) du commit.
!type(?scope) : !sujet <?body> <?footer>
Comment bien formuler le sujet d'un commit ?
Pour bien formuler le sujet, on peut tourner la phrase dans sa tête de la manière suivante : "si ce commit est appliqué, il va ..."
Par exemple "si commit est appliqué il va, changer le balisage"
git commit -m "refactor: changed the markup"
Quels sont les différents types de commit ?
Le type est responsable de nous dire quelle modification ou itération est effectuée, à partir des règles de convention, nous avons les types suivants :
test
: indique tout type de création ou de modification de codes de test.
Exemple: création de tests unitaires.feat
: indique le développement d'une nouvelle fonctionnalité pour le projet.
Exemple: Ajout d'un service, d'une fonctionnalité, d'un endpoint, etc.refactor
: utilisé lorsqu'il y a un refactoring du code qui n'a pas d'impact sur la logique/les règles du système.
Exemple: modifications du code après une révision du codestyle
: utilisé lorsqu'il y a des changements de formatage et de style de code qui ne modifient en rien le système.
Exemple: changer le guide de style, changer la convention lint, corriger les indentations, supprimer les espaces blancs, supprimer les commentaires, etc...fix
: utilisé pour corriger les erreurs qui génèrent des bogues dans le système.
Exemple: appliquer une manipulation pour une fonction qui ne se comporte pas comme prévu et qui renvoie une erreur.chore
: indique les changements apportés au projet qui n'affectent pas le système ou les fichiers de test. Ce sont des changements de développement.
Exemple: changer les règles pour eslint, ajouter prettier, ajouter plus d'extensions de fichiers à .gitignore.docs
: utilisé lorsqu'il y a des changements dans la documentation du projet.
Exemple: ajouter des informations dans la documentation de l'API, modifier le README, etc.build
: utilisé pour indiquer les changements qui affectent le processus de construction du projet ou les dépendances externes.
Exemple: Gulp, ajouter/supprimer des dépendances npm, etc...perf
: indique un changement qui a amélioré les performances du système.
Exemple: remplacer ForEach par While, etc...ci
: utilisé pour les changements dans les fichiers de configuration CI.
Exemple: Circle, Travis, BrowserStack, etc...revert
: indique l'annulation d'un commit précédent.
Note :
- Un seul type par engagement
- Le type est obligatoire
- Si vous ne savez pas quel type utiliser, il s'agit probablement d'un changement important et il est possible de diviser ce commit en deux ou plusieurs commits
- La différence entre
build
etchore
peut être assez subtile et peut prêter à confusion, nous devons donc être conscients du type correct. Dans le cas de Node.js, par exemple, nous pouvons penser que lorsqu'il y a un ajout/changement à une certaine dépendance de développement présente dansdevDependencies
, nous utilisonschore
. Pour les changements/ajouts de dépendances communes au projet, et qui ont un impact direct et réel sur le système, nous utilisonsbuild
.
Portée : contextualisation de l'engagement
A ce stade - et suivant les conventions passées - nous avons réussi à comprendre le type de changement qui a été fait dans le commit (commit type) et à comprendre clairement ce que le commit apportera s'il est appliqué (commit subject).
Même si la portée n'est pas obligatoire, elle peut être utilisée pour contextualiser le commit et déresponsabiliser le sujet, en le rendant aussi bref et concis que possible. Rappelons que le scope doit être inséré dans le commit entre parenthèses.
Questions fréquentes
Qu'est-ce que le "conventional commit"
La spécification des commits conventionnels est une convention légère sur les messages de commit. Elle fournit un ensemble de règles simples pour créer un historique explicite des livraisons, ce qui facilite l'écriture d'outils automatisés au-dessus des messages de livraison.