Commits Conventionnels

Une spécification ajoutant une signification lisible pour l'humain et pour la machine dans les messages des commits

Voir la spécification GitHub

Conventional Commits 1.0.0-beta.2

Résumé

En tant que responsable open-source, il faut rédiger un commit standardisé pour chaque fonctionnalité envoyé sur master.

Le message du commit doit être structuré comme suit:

<type>[optional scope]: <description>

[optional body]

[optional footer]

Le commit contient les éléments structurels suivants, permettant de communiquer à l’intention des consommateurs de votre bibliothèque:

  1. fix: un commit de type fix corrige un bogue dans le code (cela est en corrélation avec PATCH en versioning sémantique).
  2. feat: un commit de type feat introduit une nouvelle fonctionnalité dans le code (cela est en corrélation avec MINOR en versioning sémantique).
  3. BREAKING CHANGE: un commit qui a le texte BREAKING CHANGE: qui est facultatif au début du texte ou section de pied de page introduit un changement cassant l’API (cela est en corrélation avec MAJOR en versioning sémantique). Un changement radical peut faire partie des commits de type. par exemple, fix:, feat: & chore: qui sont tous valables, même additionnés les un avec les autres type.
  4. Others: commit de types autre que fix: et feat: sont autorisés, par exemple commitlint-config-conventional (basé sur the Angular convention) recommande chore:, docs:, style:, refactor:, perf:, test:, et d’autres. Nous recommandons également improvement pour les commits qui améliorent une implémentation en cours sans ajouter de nouvelle fonctionnalité ou correction de bogue. Remarquez que ces types ne sont pas prescrits par la spécification de Conventional Commits et n’ont aucun effet implicite dans la gestion des versions sémantiques (à moins qu’ils ne comportent une rupture, qui n’est PAS recommandée). Un scope peut être fournie au type d’un commit, pour fournir des informations contextuelles supplémentaires et le contenu entre parenthèses, par exemple, feat (analyseur): ajoute la possibilité d'analyser' des tableaux.

Exemples

Message de commit avec description et changement radical dans le texte

feat: permet à l'objet de configuration fourni d'étendre d'autres configurations

BREAKING CHANGE: la clé `extends` dans le fichier de configuration est maintenant utilisée pour étendre d'autres fichiers de configuration

Message commit sans corps de texte

docs: correction d'orthographe dans CHANGELOG

Message commit avec scope

feat(lang): ajout de la langue polonaise

Message commit pour un correctif à l’aide d’un numéro d’un issue (facultatif).

fix: fautes de frappe mineures dans le code

voir le problème pour plus de détails sur les fautes de frappe corrigées

fixes issue #12

Introduction

D’après mon expérience, les bogues sont le plus souvent introduits en développement logiciel aux limites entre les applications. Les tests unitaires sont parfaits pour tester les interactions qu’un responsable open-source connaît, mais faire du mauvais travail de capture sur ces derniers, est souvent inattendues, qu’une communauté utilise une bibliothèque.

Toute personne qui a mis à niveau une nouvelle version du correctif d’une dépendance d’application commence à jeter un flux constant d’erreurs 500, sait à quel point un historique de commit lisible (et idéalement un CHANGELOG bien entretenu) est un processus adéquat qui s’ensuit.

La spécification de Conventional Commits propose d’introduire un poids léger et normalisé les messages des commits. Cette convention s’articule avec SemVer, demandez aux développeurs de logiciels de décrire dans les messages de commit, les fonctionnalités, les correctifs et les ruptures les changements qu’ils font.

En introduisant cette convention, nous créons un langage commun qui facilite le débogage des problèmes au-delà des limites du projet.

Spécification

Les mots clés ”DOIT” (“MUST”), “NE DOIT PAS” (“MUST NOT”), “REQUIS” (“REQUIRED”), “NE DOIT” (“SHALL”), “NE DOIT PAS” (“SHALL NOT”), “NE DEVRAIT” (“SHOULD”), “NE DEVRAIT PAS” (“SHOULD NOT”), “RECOMMANDÉ” (“RECOMMENDED”), “PEUT” (“MAY”), et “FACULTATIF” (“OPTIONAL”) dans ce document doivent être interprétés comme décrit dans RFC 2119.

  1. Les commits DOIT être préfixés par un type, qui consiste en un nom, feat, fix, etc., suivi d’un côlon et d’un espace.
  2. Le type feat DOIT être utilisé lorsqu’un commit ajoute une nouvelle fonctionnalité à votre application. ou bibliothèque.
  3. Le type fix DOIT être utilisé lorsqu’un commit représente un correctif pour votre application.
  4. Un scope facultative PEUT être fournie après un type. Un scope est une phrase décrivant une section du code encadrée par des parenthèses, par exemple, fix (analyseur)):
  5. Une description DOIT suivre immédiatement le préfixe type/scope. La description est une brève description des modifications du code, par exemple, fix: problème d’analyse d’un tableau lorsque plusieurs espaces étaient contenus dans string.
  6. Un texte plus long PEUT être fourni après la description courte, fournissant des informations contextuelles supplémentaires sur les modifications du code. Le texte DOIT commencer par une ligne vide après la description.
  7. Un pied de page PEUT être fourni une ligne vierge après le texte (ou après la description si le texte manque). Le pied de page DEVRAIT contenir des références de problèmes supplémentaires concernant les modifications du code (telles que les problèmes qu’il corrige, par exemple, Fixes #13).
  8. Les changements de rupture DOIVENT être indiqués au tout début du pied de page ou de la section du corps de texte d’un commit. Un changement radical DOIT être dans le texte en majuscule BREAKING CHANGE, suivi de deux points et d’un espace.
  9. Une description DOIT être fournie après le «BREAKING CHANGE:», décrivant la modification de l’API, par exemple, BREAKING CHANGE: les variables d’environnement sont désormais prioritaires sur les fichiers de configuration.
  10. Le pied de page NE DOIT contenir que «BREAKING CHANGE», des liens externes, des références de publication et d’autres méta-informations.
  11. Des types autres que feat et fix PEUVENT être utilisés dans vos messages de commit.

Pourquoi Utiliser Conventional Commits

FAQ

Comment dois-je gérer les messages de commit dans la phase de développement initiale ?

Nous vous recommandons de procéder comme si vous aviez déjà publié un produit. Généralement quelqu’un, même si ce sont vos collègues développeurs de logiciels, utilise votre logiciel. Ils voudront savoir ce qui est corrigé, ce qui casse, etc.

Que dois-je faire si le commit est conforme à plusieurs types ?

Revenez en arrière et faites plusieurs commits autant que possible. Une partie des avantages de Conventional Commits réside dans sa capacité à nous amener à créer des commits et des relations publiques plus organisés.

Est-ce que cela ne décourage pas le développement rapide et l’itération rapide ?

Cela décourage les commits rapides de manière désorganisée. Il vous aide à être en mesure que vous commité rapidement à long terme dans plusieurs projets avec des contributeurs variés.

Les engagements conventionnels peuvent-ils amener les développeurs à limiter le type d’engagements qu’ils font car ils penseront aux types fournis?

Conventional Commits nous encouragent à utiliser davantage certains types de commits tels que les correctifs. En dehors de cela, la flexibilité de Conventional Commits permet à votre équipe de créer ses propres types et de les modifier au fil du temps.

Quel est le lien avec SemVer ?

Les corrections de type fix devraient être traduites en PATCH. Les commits de type feat devraient être traduits en versions MINOR. Les commits avec BREAKING CHANGE dans les commits, quel que soit leur type, doivent être traduits en versions MAJOR.

Comment dois-je mettre à jour mes extensions de la spécification de Conventional Commits, par exemple @jameswomack/conventionnel-commit-spec ?

Nous vous recommandons d’utiliser SemVer pour publier vos propres extensions à cette spécification (et vous encourage à faire ces extensions!)

Que dois-je faire si j’utilise accidentellement le type de commit incorrect ?

Lorsque vous utilisez un type de commit incorrect, par exemple fix au lieu de feat

Avant de fusionner ou de relâcher l’erreur, nous vous recommandons d’utiliser git rebase -i pour éditer l’historique des commits. Après la publication, le nettoyage sera différent selon les outils et les processus que vous utilisez.

Lorsque vous utilisez un type qui n’est pas dans les spécifications, par exemple pieds au lieu de feat

Dans le pire des cas, ce n’est pas la fin du monde si un commit atterrit sans respecter les spécifications de Conventional Commits. Cela signifie simplement que l’engagement sera raté par des outils basés sur les spécifications.

Est-ce que tous mes contributeurs doivent utiliser les spécifications de Conventional Commits ?

Non! Si vous utilisez un flux de travail basé sur squash sur Git, les responsables principaux peuvent nettoyer les messages des commits au fur et à mesure de leur fusion, ce qui permet de ne pas ajouter de charge de travail aux committers occasionnels. Un processus courant consiste à ce que votre système git écrase automatiquement les commits d’une demande d’extraction et présente un formulaire permettant au responsable de la maintenance d’entrer le message du commit git approprié pour la fusion.