Creare Messaggi di Commit Git Eccellenti: Best Practices per una Cronologia Chiara

I messaggi di commit Git sono le note su cui il tuo team fa affidamento quando il codice si rompe, il comportamento cambia o una release necessita di spiegazioni. Un messaggio chiaro ti dice cosa è cambiato e perché, senza costringerti a fare reverse engineering del diff.

I buoni messaggi di commit non devono essere elaborati. Hanno bisogno di una riga oggetto utile, un contesto sufficiente per modifiche non banali e uno stile coerente che il tuo team possa leggere mesi dopo.

Perché i Buoni Messaggi di Commit Sono Importanti?

I buoni messaggi di commit aiutano in diversi modi pratici:

Comprendere le Modifiche: Forniscono un contesto immediato su cosa introduce o modifica un commit specifico, risparmiando tempo durante la revisione del codice o il ripensamento di decisioni passate.
Debugging: Quando si rintracciano bug, una cronologia dei commit chiara permette di individuare esattamente quando e perché è stata introdotta una modifica problematica.
Collaborazione: Per i membri del team che si uniscono a un progetto o che rivisitano codice vecchio, messaggi ben scritti rendono più facile comprendere la traiettoria di sviluppo del progetto.
Code Review: Offrono ai revisori informazioni sull'intento dietro le modifiche, facilitando feedback più produttivi e mirati.
Strumenti Automatici: Molti strumenti Git, come i generatori di changelog e i creatori di note di rilascio, si basano sui messaggi di commit per funzionare efficacemente.
Registro Storico: Servono come una forma di documentazione, preservando l'evoluzione del codebase nel tempo.

L'Anatomia di un Messaggio di Commit Git Eccellente

Una struttura universalmente riconosciuta per i messaggi di commit Git segue un modello semplice ma potente: una riga oggetto concisa seguita da un corpo opzionale più dettagliato.

La Riga Oggetto

La riga oggetto è la prima riga del tuo messaggio di commit. Dovrebbe essere un riepilogo breve e imperativo delle modifiche. Pensala come un titolo per il commit.

Linee Guida Chiave per la Riga Oggetto:

Mantienila concisa: Circa 50 caratteri è un obiettivo utile, non un limite rigido. Mantieni l'oggetto abbastanza corto da poter essere scansionato in git log --oneline.
Usa il modo imperativo: Inizia con un verbo che descrive l'azione, come se stessi impartendo un comando. Esempi: Correggi, Aggiungi, Rifattorizza, Aggiorna, Rimuovi, Stile.
Maiuscola alla prima parola: La convenzione standard prevede di scrivere in maiuscolo la prima lettera della riga oggetto.
Non terminare con un punto: La riga oggetto è un titolo, non una frase.
Evita di usare git commit -m "messaggio" per messaggi più lunghi: Sebbene comodo per brevi note, può portare a messaggi meno strutturati. Usa git commit senza argomenti per aprire il tuo editor per messaggi più complessi.

Esempi di Buone Righe Oggetto:

feat: aggiungi modulo di autenticazione utente
fix: risolvi ciclo infinito nell'elaborazione dati
docs: aggiorna passaggi di installazione nel README
refactor: semplifica caricamento immagini
chore: aggiorna dipendenze di sviluppo

Il Corpo

Il corpo del messaggio di commit è dove fornisci più contesto e dettagli. È separato dalla riga oggetto da una riga vuota. Questa sezione è opzionale ma altamente raccomandata per qualsiasi modifica che non sia banale.

Linee Guida Chiave per il Corpo:

Spiega il 'perché' e il 'come': Non descrivere solo cosa è cambiato; spiega perché la modifica era necessaria e come è stata implementata. Quale problema risolve questo commit? Qual era il comportamento precedente? Qual è il nuovo comportamento?
Vai a capo a 72 caratteri: Questa è una convenzione di lunga data che migliora la leggibilità in molti strumenti e terminali Git.
Usa elenchi puntati per le liste: Se devi enumerare più modifiche o punti, usa elenchi puntati per chiarezza.
Fai riferimento a issue o ticket: Se il commit è correlato a un tracker di issue (es. GitHub Issues, Jira), includi il numero del ticket per la tracciabilità.

Esempio di un Buon Messaggio di Commit (Oggetto + Corpo):

feat: implementa pagina profilo utente

Questo commit introduce la pagina del profilo utente, permettendo agli utenti
di visualizzare e modificare le proprie informazioni personali.

In precedenza, gli utenti non potevano accedere o modificare i dettagli del
proprio profilo. Questa modifica aggiunge una nuova rotta (`/profile`) e un
componente corrispondente che recupera i dati utente dall'API e fornisce
moduli per aggiornare campi come nome, email e biografia.

Correlato a #123.

Tipi Comuni di Messaggi di Commit (Conventional Commits)

Seguire una convenzione per i tipi di messaggi di commit può migliorare ulteriormente la chiarezza e abilitare strumenti automatici. La specifica Conventional Commits è uno standard popolare che promuove un approccio strutturato.

I Conventional Commits usano un prefisso per denotare il tipo di modifica:

feat (funzionalità): Viene introdotta una nuova funzionalità nel codebase.
fix (correzione bug): Viene risolto un bug.
docs (documentazione): Solo modifiche alla documentazione.
style (formattazione): Modifiche che non influenzano il significato del codice (spazi bianchi, formattazione, punto e virgola mancanti, ecc.).
refactor (refactoring del codice): Una modifica al codice che non corregge un bug né aggiunge una funzionalità.
perf (prestazioni): Una modifica al codice che migliora le prestazioni.
test (aggiunta di test mancanti o correzione di test esistenti): Aggiunta o correzione di test.
build (modifiche che influenzano il sistema di build o le dipendenze esterne): Esempi sono script npm, webpack, ecc.
ci (modifiche ai file e script di configurazione CI): Esempi sono Travis, Circle, BrowserStack, SauceLabs, ecc.
chore (lavoro di manutenzione): Attività che non rientrano negli altri tipi, come la manutenzione del repository.

Scope (Opzionale): Uno scope può essere aggiunto al prefisso per indicare la parte del codebase interessata. Ad esempio: feat(auth): Aggiungi autenticazione JWT.

Footer (Opzionale): Usa il footer per fare riferimento a issue, segnare modifiche che rompono la compatibilità o aggiungere altri metadati. Conventional Commits usa BREAKING CHANGE: per le modifiche che rompono la compatibilità.

Esempio che usa Conventional Commits:

fix(api): correggi endpoint per il recupero dati utente

In precedenza, l'endpoint `/users/:id/data` restituiva informazioni
obsolete. Questo commit aggiorna l'endpoint a `/users/:id/profile` che
recupera i dati del profilo utente più recenti.

Chiude #456

Consigli per Scrivere Ottimi Messaggi di Commit

Fai commit spesso, ma in modo logico: Crea commit piccoli e atomici che rappresentano una singola modifica logica. Questo rende i messaggi più facili da scrivere e comprendere.
Scrivi i messaggi dal punto di vista del futuro del progetto: Immagina di guardare indietro a questo commit tra sei mesi. Di quali informazioni avresti bisogno per capire rapidamente la modifica?
Sii specifico: Evita messaggi vaghi come "Aggiorna codice" o "Correzioni bug". Spiega precisamente cosa è stato aggiornato o corretto.
Usa i backtick per i riferimenti al codice: Se menzioni nomi di file, funzioni o nomi di variabili, racchiudili tra backtick (`).
Rivedi i tuoi messaggi: Prima di eseguire il commit, prenditi un momento per leggere il tuo messaggio. Ha senso? È chiaro?

Concetti Chiave

Scrivi ogni messaggio di commit per la persona che lo leggerà durante una revisione, un rollback o un incidente. Usa un oggetto imperativo breve, aggiungi un corpo quando la ragione non è ovvia e mantieni ogni commit focalizzato su una singola modifica logica.