Commits qui racontent une histoire

Un message de commit est la seule documentation qui voyage avec le code pour toujours. Les commentaires sont supprimés, les wikis deviennent obsolètes, les tickets sont archivés — mais git log est permanent. Les équipes qui écrivent de bons commits peuvent naviguer dans leur propre historique. Celles qui ne le font pas font de l'archéologie dans leur propre base de code en six mois.

Un bon commit a une ligne de sujet claire à l'impératif (« Add rate limiting to auth endpoint », pas « Added rate limiting » ou « rate limiting stuff »), un corps optionnel qui explique pourquoi le changement a été fait (pas quoi — le diff montre quoi), et contient exactement un changement logique.

fix: prevent duplicate webhook deliveries

The webhook dispatcher was firing on both the DynamoDB stream event
and the API Gateway trigger. Deduplicate by checking idempotency key
before dispatch.

Comparez cela à ce que la plupart des dépôts contiennent réellement :

fix stuff
wip
updates

Le premier commit est recherchable, réversible et auto-documenté. Le deuxième ensemble est du bruit. Dans six mois, « fix stuff » ne vous dit rien — vous devrez lire le diff, reconstruire le contexte et deviner l'intention. Les 10 secondes que vous avez économisées en écrivant un message paresseux coûtent 10 minutes chaque fois que quelqu'un le rencontre.

Les Conventional Commits ajoutent un préfixe léger à chaque sujet de commit qui rend votre historique lisible par machine sans sacrifier la lisibilité humaine. Le format est simple :

feat: add dark mode toggle to settings
fix: correct timezone offset in standup scheduler
chore: upgrade TypeScript to 5.7
docs: add API rate-limit documentation
refactor: extract validation logic from route handler

Le préfixe vous indique la catégorie de changement d'un coup d'œil. feat signifie un nouveau comportement visible par l'utilisateur. fix signifie qu'un bogue a été corrigé. chore signifie une maintenance qui n'affecte pas les utilisateurs. Cela ne coûte rien — vous écrivez déjà une ligne de sujet, vous ajoutez simplement 4 à 8 caractères au début.

Le bénéfice est des changelogs automatiques, un versionnage sémantique (un feat incrémente la version mineure, un fix incrémente le patch), et un filtrage instantané (git log --grep="^fix:" vous montre chaque correction de bogue du dernier trimestre). Les équipes qui adoptent les Conventional Commits rapportent que leurs PR sont révisées plus rapidement parce que le réviseur sait à quel type de changement s'attendre avant de lire une seule ligne de diff.

Vous n'avez pas besoin d'outils pour commencer. Convenez simplement des préfixes en équipe et appliquez-les lors de la révision de code. Ajoutez l'automatisation plus tard si vous le souhaitez — mais la convention est utile en soi.

Un commit devrait représenter exactement un changement logique. Pas « tout ce que j'ai fait aujourd'hui », pas « tous les fichiers que j'ai touchés pour cette fonctionnalité », et certainement pas « WIP » — un message qui ne communique rien et rend le commit non réversible sans effets secondaires.

Les commits atomiques comptent pour deux raisons pratiques. Premièrement, la réversibilité : si un commit fait une chose, le réverser annule une chose. Si un commit fait trois choses et que l'une d'elles est cassée, le réverser annule les trois — y compris les deux qui étaient correctes. Vous réparez maintenant les dommages collatéraux de votre propre rollback.

Deuxièmement, la bisectabilité : git bisect effectue une recherche binaire dans votre historique de commits pour trouver quel commit a introduit un bogue. C'est l'un des outils de débogage les plus puissants de Git — mais il ne fonctionne que lorsque chaque commit est une unité cohérente. Si vos commits mélangent des changements non liés, bisect vous pointera vers un commit qui contient à la fois le changement coupable et trois innocents, et vous êtes de retour à lire les diffs manuellement.

Le commit « WIP » est l'ennemi des deux propriétés. Il dit « je n'avais pas fini de réfléchir » — ce qui signifie que le commit contient un travail partiellement complété qui ne peut pas être réversé proprement, ne peut pas être bisecté de manière significative et ne peut pas être compris isolément. Si vous devez sauvegarder un travail en cours, utilisez git stash ou une branche brouillon. Ne polluez pas l'historique partagé avec des points de contrôle qui n'ont aucune valeur sémantique.