Commit che Raccontano una Storia

Un messaggio di commit è l'unica documentazione che viaggia con il codice per sempre. I commenti vengono eliminati, i wiki diventano obsoleti, i ticket vengono archiviati — ma git log è permanente. I team che scrivono buoni commit possono navigare nella propria cronologia. I team che non lo fanno stanno facendo archeologia nel proprio codebase entro sei mesi.

Un buon commit ha un oggetto chiaro in forma imperativa ("Add rate limiting to auth endpoint", non "Added rate limiting" o "rate limiting stuff"), un corpo facoltativo che spiega perché è stata fatta la modifica (non cosa — il diff mostra cosa), e contiene esattamente una modifica logica.

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.

Confrontalo con ciò che la maggior parte dei repository contiene effettivamente:

fix stuff
wip
updates

Il primo commit è ricercabile, revertibile e auto-documentato. Il secondo insieme è rumore. Tra sei mesi, "fix stuff" non ti dice nulla — dovrai leggere il diff, ricostruire il contesto e indovinare l'intento. I 10 secondi che hai risparmiato scrivendo un messaggio pigro costano 10 minuti ogni volta che qualcuno lo incontra.

I Conventional Commits aggiungono un prefisso leggero all'oggetto di ogni commit che rende la tua cronologia leggibile dalla macchina senza sacrificare la leggibilità umana. Il formato è semplice:

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

Il prefisso ti dice la categoria di modifica a colpo d'occhio. feat significa nuovo comportamento visibile all'utente. fix significa che un bug è stato corretto. chore significa manutenzione che non influisce sugli utenti. Questo non costa nulla — stai già scrivendo un oggetto, stai solo aggiungendo 4–8 caratteri all'inizio.

Il vantaggio sono changelog automatici, versionamento semantico (un feat incrementa la versione minore, un fix incrementa la patch), e filtraggio istantaneo (git log --grep="^fix:" ti mostra ogni correzione di bug nell'ultimo trimestre). I team che adottano i Conventional Commits riferiscono che le loro PR vengono revisionate più velocemente perché il revisore sa che tipo di modifica aspettarsi prima di leggere una singola riga di diff.

Non hai bisogno di strumenti per iniziare. Basta concordare i prefissi come team e applicarli nella revisione del codice. Aggiungi l'automazione più tardi se vuoi — ma la convenzione è utile da sola.

Un commit dovrebbe rappresentare esattamente una modifica logica. Non "tutto quello che ho fatto oggi", non "tutti i file che ho toccato per questa funzionalità", e sicuramente non "WIP" — un messaggio che non comunica nulla e rende il commit non revertibile senza effetti collaterali.

I commit atomici contano per due ragioni pratiche. Primo, revertibilità: se un commit fa una cosa, revertirlo annulla una cosa. Se un commit fa tre cose e una di esse è rotta, revertirlo annulla tutte e tre — incluse le due che andavano bene. Ora stai riparando danni collaterali dal tuo stesso rollback.

Secondo, bisectabilità: git bisect cerca binariamente nella tua cronologia dei commit per trovare quale commit ha introdotto un bug. È uno degli strumenti di debug più potenti di Git — ma funziona solo quando ogni commit è un'unità coerente. Se i tuoi commit mescolano modifiche non correlate, bisect ti indicherà un commit che contiene sia la modifica colpevole che tre innocenti, e sei di nuovo a leggere i diff manualmente.

Il commit "WIP" è il nemico di entrambe le proprietà. Dice "non avevo finito di pensare" — il che significa che il commit contiene lavoro parzialmente completato che non può essere revertito in modo pulito, non può essere bisezionato in modo significativo e non può essere compreso in isolamento. Se hai bisogno di salvare lavoro in corso, usa git stash o un branch bozza. Non inquinare la cronologia condivisa con checkpoint che non hanno valore semantico.