Comment écrire de bons messages de validation: un guide pratique de Git

Pour créer un historique des révisions utile, les équipes doivent d'abord convenir d'une convention de message de validation à utiliser. Cela vaut également pour les projets personnels.

Récemment, sur Hashnode, j'ai demandé: "Quelle convention de message de validation utilisez-vous au travail?" et j'ai eu des réponses incroyables avec des utilisateurs expliquant les conventions qu'ils utilisent au travail et pour leurs projets personnels.

Quelle convention de message de validation utilisez-vous au travail?

de @hashnode //t.co/HewCBxRCbr

- BOLAJI ✨ (@iambolajiayo) 25 novembre 2019

Dans cet article, je vais vous expliquer comment écrire de bons messages de validation et pourquoi vous devriez le faire.

PS: Cet article a d'abord été publié sur mon blog ici.

Introduction au contrôle de version avec Git

Les logiciels de contrôle de version sont une partie essentielle des pratiques modernes des développeurs de logiciels.

De loin, Git est le système de contrôle de version le plus utilisé au monde. Il s'agit d'un projet open source distribué et activement maintenu développé à l'origine en 2005 par Linus Torvalds, le célèbre créateur du noyau du système d'exploitation Linux.

Nouveau sur Git? Consultez le guide de démarrage officiel ou cette diapositive d'un discours que j'ai donné.

Qu'est-ce qu'un message de validation?

La commande commit est utilisée pour enregistrer les modifications dans un référentiel local après le transfert dans Git. Cependant, avant de pouvoir enregistrer les modifications dans Git, vous devez indiquer à Git les modifications que vous souhaitez enregistrer car vous avez peut-être effectué des tonnes de modifications. Un excellent moyen d'y parvenir consiste à ajouter un message de validation pour identifier vos modifications.

Options de validation

  • -m

Cette option définit le message du commit.

git add static/admin/config.yml git commit -m "Setup multiple roles for netlify-cms git gateway" 
  • -a ou --all

Cette option valide automatiquement tous les fichiers suivis, modifiés ou supprimés (y compris les nouveaux).

git commit -a -m "Add a new role for netlify-cms git gateway" 
  • --modifier

Cette option réécrit le tout dernier commit avec toutes les modifications actuellement préparées ou un nouveau message de commit et ne doit être effectuée que sur les commits qui n'ont pas encore été poussés vers un référentiel distant.

git add . git commit --amend -m "Update roles for netlify-cms git gateway" 

Pourquoi devriez-vous écrire de bons messages de commit?

Vous pourriez dire: «C'est juste un projet personnel». Oui, vous travaillez seul maintenant, mais que se passe-t-il lorsque vous travaillez en équipe ou que vous contribuez à l'open source?

Un message de commit Git bien conçu est le meilleur moyen de communiquer le contexte d'un changement aux autres développeurs travaillant sur ce projet, et même à vous-même.

Avez-vous déjà essayé de courir git logsur l'un de vos anciens projets pour voir les messages de commit "bizarres" que vous avez utilisés depuis sa création? Il peut être difficile de comprendre pourquoi vous avez apporté des modifications dans le passé, et vous souhaiterez que vous lisiez cet article plus tôt :).

Les messages d'engagement peuvent communiquer de manière adéquate les raisons pour lesquelles un changement a été apporté et une compréhension qui rend le développement et la collaboration plus efficaces.

Comment écrire des messages de validation avec Git

Avant, je n'utilisais que git commit -m "Fix X to allow Y to use Z"sur mes projets personnels avec juste un sujet et aucune description supplémentaire. C'est idéal pour les corrections petites et claires comme git commit -m "Fix typo in README.md, mais dans le cas de modifications plus importantes, vous devrez ajouter des détails supplémentaires.

Méthode de l'éditeur

Exécutez git commitsans message ni option et cela ouvrira votre éditeur de texte par défaut pour écrire un message de validation.

Pour configurer votre éditeur "par défaut":

git config --global core.editor nano 

Cela configurerait Git pour utiliser nano comme éditeur par défaut. Remplacez «nano» par «emacs», «vim» ou quelle que soit votre préférence.

Dans l'éditeur ouvert, la première ligne est le sujet (brève description), laissez une ligne vide après, et tout le reste est la description étendue (corps).

Méthode de ligne de commande

git commit -m "Subject" -m "Description..." 

La première -moption est le sujet (brève description) et la suivante est la description étendue (corps).

Comment écrire de bons messages de commit

Il existe plusieurs conventions utilisées par différentes équipes et développeurs pour écrire de bons messages de validation. Je ne présenterai que quelques règles générales et conseils pour rédiger des messages de validation - vous devez décider de la convention que vous souhaitez suivre. Et si vous travaillez pour une entreprise ou contribuez à l'open source, vous devez vous adapter à leur convention :).

Par souci de cohérence, vous pouvez utiliser une convention pour le travail et une autre pour les projets personnels, car vous pourriez changer de travail à un moment donné, et la convention peut également changer.

Assurez-vous de consulter ce fil pour découvrir des conventions de message de validation incroyables ou ajoutez la vôtre pour aider quelqu'un à prendre une décision.

Voici un excellent modèle d'un bon message de commit écrit à l'origine par Tim Pape

Capitalized, short (50 chars or less) summary More detailed explanatory text, if necessary. Wrap it to about 72 characters or so. In some contexts, the first line is treated as the subject of an email and the rest of the text as the body. The blank line separating the summary from the body is critical (unless you omit the body entirely); tools like rebase can get confused if you run the two together. Write your commit message in the imperative: "Fix bug" and not "Fixed bug" or "Fixes bug." This convention matches up with commit messages generated by commands like git merge and git revert. Further paragraphs come after blank lines. - Bullet points are okay, too - Typically a hyphen or asterisk is used for the bullet, followed by a single space, with blank lines in between, but conventions vary here - Use a hanging indent If you use an issue tracker, add a reference(s) to them at the bottom, like so: Resolves: #123 

Ça a l'air génial, non? Voici comment vous pouvez aussi rendre le vôtre génial:

  1. Spécifiez le type de validation:
  • exploit: la nouvelle fonctionnalité que vous ajoutez à une application particulière
  • fix: A bug fix
  • style: Feature and updates related to styling
  • refactor: Refactoring a specific section of the codebase
  • test: Everything related to testing
  • docs: Everything related to documentation
  • chore: Regular code maintenance.[ You can also use emojis to represent commit types]
  1. Separate the subject from the body with a blank line
  2. Your commit message should not contain any whitespace errors
  3. Remove unnecessary punctuation marks
  4. Do not end the subject line with a period
  5. Capitalize the subject line and each paragraph
  6. Use the imperative mood in the subject line
  7. Use the body to explain what changes you have made and why you made them.
  8. Do not assume the reviewer understands what the original problem was, ensure you add it.
  9. Do not think your code is self-explanatory
  10. Follow the commit convention defined by your team

Conclusion

The most important part of a commit message is that it should be clear and meaningful. In the long run, writing good commit messages shows how much of a collaborator you are. The benefits of writing good commit messages are not only limited to your team, but indeed expand to yourself and future contributors.

Want to learn more about Git and become a professional "version controller"? Check out these excellent resources:

  • //try.github.io/
  • //git-scm.com/book/en/v2
  • //www.git-tower.com/learn/
  • //learngitbranching.js.org/
  • //github.com/commitizen/cz-cli