Conventional Commits: il messaggio di commit come documento tecnico

La maggior parte dei team non ha mai discusso esplicitamente di come scrivere i messaggi di commit. Si forma una convenzione tacita nel tempo, spesso il risultato dello stile del primo sviluppatore che ha aperto il repository, e quella convenzione resta intatta finché il team cresce e la coerenza si deteriora silenziosamente. Il messaggio di commit è il documento storico più capillare che un progetto produce: ogni decisione tecnica, ogni bug fix, ogni refactoring lasciano una traccia. Trattare quella traccia come un campo libero da compilare a piacere significa sprecare uno degli strumenti di comprensione più preziosi disponibili a chiunque lavori sul codice, oggi o tra anni.

La struttura del formato

Conventional Commits è una specifica leggera che definisce un insieme minimo di regole per la struttura dei messaggi. Il formato prevede un tipo, un ambito opzionale e una descrizione breve, seguiti da corpo e footer opzionali. I tipi canonici sono pochi e immediati: feat per una nuova funzionalità, fix per una correzione di bug, docs per la documentazione, refactor per riorganizzazioni che non cambiano il comportamento esterno, chore per attività di manutenzione come aggiornamenti delle dipendenze. Il punto esclamativo dopo il tipo segnala un breaking change, informazione che altrimenti richiederebbe di leggere il diff completo per essere identificata.

# A new feature with a scope
feat(auth): add password strength meter

# A bug fix
fix(api): handle null response from payment gateway

# Documentation only
docs: update installation steps in README

# A breaking change, signalled by the exclamation mark
feat(api)!: drop support for legacy v1 endpoints

Questa struttura non è arbitraria. Deriva dall’osservazione che i messaggi di commit servono a rispondere a domande diverse a seconda di chi li legge e quando: uno sviluppatore che indaga un bug ha bisogno di sapere cosa è cambiato e perché, un responsabile tecnico che prepara una release ha bisogno di capire cosa va nel changelog e quale versione semantica assegnare, un nuovo membro del team ha bisogno di ricostruire l’evoluzione di una parte del codice senza dover aprire ogni singolo diff. Il formato risponde a tutte queste esigenze con la stessa struttura.

Il valore del tooling

Il beneficio più immediato e misurabile dell’adozione di Conventional Commits è l’accesso a un ecosistema di strumenti che operano direttamente sulla struttura dei messaggi. Semantic-release analizza i commit dall’ultimo tag, determina automaticamente il tipo di versione da rilasciare in base alle convenzioni presenti (patch per i fix, minor per le feature, major per i breaking change) e pubblica la release con il changelog generato. Release-please di Google fa lo stesso per i progetti ospitati su GitHub, aprendo automaticamente una pull request di rilascio ogni volta che ci sono commit accumulati sul branch principale. Conventional-changelog produce documenti leggibili in qualsiasi formato senza richiedere alcuna configurazione aggiuntiva.

Questi strumenti non sono vantaggi marginali. Eliminano una categoria di lavoro manuale ripetitivo e soggetto a errori: decidere quale versione assegnare, scrivere il changelog, coordinare il rilascio tra i membri del team. Quando il processo di rilascio è determinato dalla struttura dei commit non è più una decisione che richiede riunione o giudizio soggettivo, ma una conseguenza automatica di ciò che il team ha già documentato nel proprio flusso di lavoro normale.

La leggibilità come requisito di progetto

C’è una dimensione meno visibile del valore di Conventional Commits che riguarda l’onboarding e la manutenzione a lungo termine. Un repository con una storia di commit coerente e strutturata è un repository in cui un nuovo sviluppatore può orientarsi senza dover chiedere a nessuno. Filtrare i commit per tipo, cercare tutti i fix applicati a un certo modulo, ricostruire la cronologia di una funzionalità: operazioni che con messaggi liberi richiedono di leggere e interpretare ogni voce diventano interrogazioni dirette su metadati strutturati.

Questo ha conseguenze concrete sulla velocità con cui un team può rispondere a un incidente. Quando qualcosa si rompe in produzione e bisogna capire quale commit ha introdotto la regressione, la differenza tra una storia leggibile e un elenco di messaggi come “fix”, “update”, “varie modifiche” può valere ore di investigazione. La struttura non serve al momento in cui il commit viene scritto, ma a tutti i momenti successivi in cui quella decisione dovrà essere compresa da qualcuno che non c’era.

Adozione graduale con commitlint

Adottare Conventional Commits in un team non richiede una migrazione retroattiva né un grande sforzo iniziale. Lo strumento più diffuso per rendere il formato obbligatorio è commitlint, configurabile in pochi minuti e integrabile con Husky o Lefthook per eseguire la validazione come hook commit-msg. In questo modo qualsiasi messaggio che non rispetta la struttura viene rifiutato immediatamente, prima che raggiunga il repository remoto, con un messaggio di errore che indica esattamente cosa correggere.

La configurazione base richiede due pacchetti e un file di configurazione minimale. Commitlint legge il messaggio, lo valida rispetto alle regole definite e blocca il commit se la struttura non è conforme. L’adozione diventa graduale perché ogni nuovo commit scritto nel formato corretto porta la storia del repository verso la coerenza senza dover toccare i commit esistenti. Nei contesti in cui il team usa editor come VS Code esistono estensioni che suggeriscono il formato mentre si scrive, riducendo ulteriormente l’attrito iniziale.

// commitlint.config.js
export default {
  extends: ['@commitlint/config-conventional'],
};

Il momento migliore per introdurre Conventional Commits è l’inizio di un progetto, ma il secondo momento migliore è adesso. Una storia di commit parzialmente strutturata è già più utile di una completamente libera, e il tooling funziona correttamente anche su repository che hanno commit non conformi nel passato perché opera solo sull’intervallo a partire dall’ultimo tag di rilascio. L’investimento richiesto è minimo rispetto al valore che restituisce nel tempo: meno decisioni manuali sul versioning, changelog generati automaticamente e una storia del progetto che risponde alle domande invece di moltiplicarle.

La specifica completa, con tutte le regole del formato e gli esempi, è disponibile sul sito ufficiale di Conventional Commits.