3 raisons pour lesquelles vous devriez utiliser les engagements conventionnels

Introduction

En tant que programmeur, vous pouvez développer une application, une bibliothèque, un microservice ou un monorepo rempli de services et de bibliothèques ou (à Dieu ne plaise !) un énorme monolithe. Quel que soit le type d'application que vous développez, si vous le "faites bien", vous utiliserez un certain contrôle de version (90% du temps avec git).

La question est de savoir comment gérer l'historique des versions. Comment signaler la correction d'un bogue, l'ajout d'une fonctionnalité, une tâche effectuée sur l'espace de travail, ou même un changement radical ? Plus important encore, quelle est la facilité avec laquelle vous pouvez voir cela ?

Commits conventionnels est une approche standardisée du contrôle de version qui améliore la clarté, la cohérence et la collaboration entre les développeurs. Dans ce billet, nous allons comprendre ce que sont les Commits conventionnels, explorer leur fonctionnement et expliquer les trois principaux avantages que vous pouvez en tirer.

À quoi ressemblent les messages Git sans normes ?

standard_commit_example

L'image ci-dessus illustre une séquence de commit git courante. Elle présente une ligne claire et singulière, ce qui est une bonne chose, mais laisse de nombreuses questions sans réponse. Que peut-on déduire des messages de validation ? Que signifie fix path signifie-t-il ? Quel chemin ? Dans quel composant ?

Il n'est pas possible de répondre à cette question en se contentant de consulter l'historique des livraisons.

Une machine ne peut pas non plus le faire. Souvenez-vous en pour plus tard.

À quoi ressemble l'engagement conventionnel ?

À titre de comparaison, voici à quoi ressemblent les messages "commit" selon les normes "Conventional Commit" :

conventional_commit_example

En regardant simplement les deux premiers éléments d'information de chaque livraison, nous apprenons déjà beaucoup de choses. En allant de bas en haut, nous pouvons voir qu'une fonctionnalité a été ajoutée au composant fab a été corrigé dans la typographie, une fonctionnalité a été ajoutée au sélecteur de date, une corvée a été effectuée dans le composant docsune autre fonctionnalité liée à accordion itemet ainsi de suite.

Ne pensez-vous pas que nos commentaires sont désormais plus clairs et plus descriptifs quant aux changements apportés à chaque poussée ?

Mais les développeurs ne passent généralement pas beaucoup de temps à consulter les messages de validation, n'est-ce pas ? Voyons maintenant la véritable puissance des Commits conventionnels.

Les avantages de l'utilisation de Commits conventionnels**

Les commits conventionnels présentent trois avantages principaux : les changelogs générés automatiquement, l'auto-version et l'amélioration de la communication au sein de l'équipe.

1. Changelog généré automatiquement

Il existe de nombreux outils capables de générer un journal des modifications en fonction des commits conventionnels. Un journal des modifications ressemble à ceci :

vivids_auto_generated_changelog

Avez-vous remarqué que le standard Conventional Commit transforme déjà les commmits réguliers en un journal des modifications facile à lire ? Il le divise même en versions avec des dates pour suivre les nouvelles fonctionnalités et les corrections de bogues.

Comment peut-il connaître la version ? C'est le prochain avantage.

2. Versionnement automatique selon SemVer

La norme d'engagement conventionnel a la structure suivante :

{type}({scope}): {description}

Le type correspond au type de changement effectué. Il existe trois types principaux : les fonctionnalités, les correctifs et les tâches.

Le champ d'application champ d'application fait référence à l'élément impacté par ce changement. Il peut s'agir d'un composant, d'une bibliothèque, d'une application ou d'un service.

La description décrit plus précisément ce qui a été modifié.

Voilà pour l'essentiel. Je ne vais pas vous ennuyer avec les spécifications complètesmais je vous conseille de le lire. C'est court et logique.

En quoi cela nous aide-t-il à gérer les versions ?

SemVer est un moyen de versionner notre logiciel. La version est composée de 3 chiffres : X.Y.Z.

X est appelé MajorY est appelé Minoret Z est appelé Patch.

Lorsque vous effectuez une modification de rupture, vous créez une version majeure. Cela signifie que l'interface de ce champ d'application a changé.

Lorsque vous ajoutez une nouvelle fonctionnalité (sans casser les fonctionnalités existantes), vous créez une version mineure.

Lorsque vous corrigez un bogue sans fonctionnalité et sans rien casser, vous créez une version corrective.

Vous voyez où nous voulons en venir ?

Désormais, une machine peut lire nos commits et décider de la version que notre scope doit recevoir.

Et vous n'avez pas à le faire vous-même. Parce que Conventional Commits est un standard, il existe de nombreux outils qui fournissent un journal des modifications automatique, une version automatique, et généralement les deux.

L'un de ces outils est release-pleasequi dispose également d'une action action github.

Encourager une meilleure communication au sein de l'équipe

Outre le fait que les messages de validation sont plus lisibles, la définition de la structure nous apporte quelque chose d'autre. Elle donne au message de livraison un contexte. Même si la description est mehparce que le type de la livraison et sa portée sont bien compris, le lecteur peut au moins anticiper ce qui va suivre.

Voici un exemple :

standarized_commits_example

Voici une tentative de normalisation. Pourtant, un être humain ne peut pas comprendre quel type de changement a été effectué (s'agit-il d'un correctif ou d'une fonctionnalité ?) ni à quel composant. Il n'est pas non plus possible d'en déduire un journal des modifications.

Si nous modifions un peu ce schéma, il se présentera comme suit :

fix(button): verified 48 done and fixed 3 (#172/vivid-103)
feat(button): verified 2 and added demo example (#172/vivid-103)
chore(dialog): fixed 1/5 (font) (#172/vivid-103)

Ce n'est pas beaucoup mieux, car la description n'est pas descriptive.

Par ailleurs, si l'on doit écrire le commit avec fix(button): {description} il est peu probable que cette personne écrive une telle description. Il est plus probable qu'une personne décrive le fix ou feat effectuée sur le button.

Comme d'habitude, l'existence de normes aide les gens à mieux faire les choses. C'est un peu comme la théorie de la vitre cassée.

Essayez-le. Voyez ce qui se passe.

Exemple de production : La norme de message d'engagement de Vivid

Nous utilisons les Commits conventionnels dans le système de conception de Vonage, Vivid.

Il nous aide à générer notre changelog et journal de version et de déterminer automatiquement la version.

En outre, nos messages de validation sont bien meilleurs depuis lors.

Mais notre application conventionnelle du commit n'est pas sur chaque commit. Pendant le développement, un développeur peut ajouter autant de commits qu'il le souhaite avec n'importe quel message.

Cependant, lorsque quelqu'un crée une demande d'extraction (PR), nous appliquons un Commit conventionnel sur le titre de la demande d'extraction :

github_commit_title_linter

Une action github obligatoire qui vérifie le titre de notre PR suit les Commits conventionnels.

Nous avons ajouté un autre standard qui nous aide à connecter le commit à un ticket JIRA. Chaque titre de PR se termine par (VIV-XXX) où XXX est le numéro du problème. Par exemple, le titre d'un PR se termine par (VIV-XXX) :

fix(disabled): adds a consistent cursor to disabled elements (VIV-999)

Finalement, dans notre journal de version, le VIV-XXX se transforme en un lien vers JIRA :

convetional_commits_with_jira_links

Finalement, lorsqu'un PR est fusionné, le titre du PR est défini comme le commit. Nous utilisons squash + merge pour que tout l'historique des livraisons soit supprimé de la branche main et que seul le commit conventionnel subsiste. Cela ressemble à ceci :

github_squash_and_merge_button

Si une demande d'extraction a plus d'un changement (plus d'un correctif ou d'une fonctionnalité), on peut toujours les ajouter dans les commentaires du commit de fusion. Nous procédons de la manière suivante :

pr_with_multiple_commits

L'outil Commit conventionnel (dans notre cas, release-please) considérera ces commentaires comme s'ils faisaient partie du message.

De cette façon, nous adoptons une approche relativement lax en ce qui concerne les messages de validation, en veillant à ce que la dernière étape soit la description du changement.

Résumé

Les commits conventionnels nous offrent deux avantages directs : un journal des modifications généré automatiquement et l'auto-versioning.

Il existe de nombreuses façons d'atteindre ces objectifs.

L'un de ces outils est Beachball. Cet outil utilise un CLI qui génère un fichier JSON au lieu de lire l'historique git. Le grand avantage est qu'il est beaucoup plus facile de changer l'historique si l'on a fait une erreur (changer l'historique git peut être assez désordonné...).

Outre ces deux avantages clairs et immédiats, je prétends qu'il contribue également à encourager les gens à rédiger de meilleurs messages d'engagement.

Il se peut que je me trompe 🙂 Faites-le moi savoir sur notre Communauté Vonage Slack ou envoyez-nous un message sur X, anciennement connu sous le nom de Twitter.

Ressources complémentaires

Systèmes de conception : Les leçons de Vivid

Comment les tests de logiciels peuvent contribuer à la communication

Introduction à Git