Best practice per i messaggi di commit

Immaginate di ripercorrere la cronologia del vostro progetto. Senza messaggi di commit chiari, sarebbe come leggere un diario con le pagine vuote!

Buoni messaggi di commit sono fondamentali per capire perché sono state apportate le modifiche, che cosa è stato modificato e come le modifiche influiscono sul progetto. Questo aiuta voi e il vostro team a eseguire il debug, revisionare il codice e inserire nuovi membri nel progetto.

Un messaggio di commit Git standard è composto da due parti principali:

• Riga dell'oggetto: una singola riga concisa che riassume la modifica.
• Corpo (facoltativo): una spiegazione più dettagliata, separata dall'oggetto da una riga vuota.

Pensatelo come un'e-mail: una riga dell'oggetto per una lettura rapida e un corpo per i dettagli.

La riga dell'oggetto è la parte più importante. Ecco le regole:

• Concisa: mantenetela al di sotto di 50-72 caratteri.
• Modo imperativo: iniziate con un verbo al presente (ad esempio, "Add feature", non "Added feature" o "Adding feature").
• Prima lettera maiuscola: è la prassi standard per una migliore leggibilità.
• Nessun punto: non terminate la riga dell'oggetto con un punto.

Vediamo alcuni esempi di righe dell'oggetto corrette e scorrette:

• Corretta: Fix: broken login button
• Corretta: Feat: implement user profile page
• Scorretta: Fixed a bug in the login system that was causing issues. (Troppo lunga, al passato)
• Scorretta: updates (Troppo vaga)

Puntate su chiarezza e concisione!

Nel corpo del commit spiegate la motivazione della modifica, il contesto e gli eventuali dettagli che non risultano evidenti dal codice.

Utilizzatelo quando la modifica richiede più spiegazioni di quelle che la riga dell'oggetto può fornire. Mandate a capo le righe intorno ai 72 caratteri per migliorare la leggibilità negli strumenti Git.

Quando scrivete il corpo:

• Spiegate perché è stata apportata la modifica, non solo che cosa è stato modificato.
• Descrivete eventuali compromessi o decisioni progettuali.
• Indicate possibili effetti collaterali o aree da monitorare.
• Lasciate una riga vuota tra l'oggetto e il corpo.

In questo modo fornite un contesto prezioso a chi leggerà il messaggio in futuro.

Ecco come potrebbe essere un messaggio di commit completo e ben strutturato:

Molti team adottano una convenzione in cui la riga dell'oggetto inizia con un prefisso di tipo. Questo aiuta a categorizzare rapidamente le modifiche.

I prefissi più comuni includono:

• feat: (nuova funzionalità)
• fix: (correzione di un bug)
• docs: (modifica alla documentazione)
• style: (stile del codice, nessuna modifica funzionale)
• refactor: (refactoring del codice)
• test: (aggiunta di test)
• chore: (manutenzione, modifiche al processo di build)

È buona norma collegare i commit alle issue o alle pull request correlate nel sistema di gestione del progetto (ad esempio GitHub Issues o Jira).

Potete farlo includendo espressioni come Closes #123, Fixes #45 o Refs #67 nel messaggio di commit, in genere nel corpo. In questo modo le modifiche al codice vengono collegate automaticamente all'attività monitorata.

Avete imparato che messaggi di commit ben scritti sono fondamentali per la chiarezza del progetto e la collaborazione. Seguendo queste migliori pratiche, trasformate la cronologia del progetto in una risorsa preziosa!

• Mantenete concise le righe dell'oggetto e utilizzate il modo imperativo.
• Utilizzate il corpo per spiegare «perché» è stata apportata una modifica.
• Valutate l'utilizzo di prefissi di tipo per la categorizzazione.
• Collegate le issue o le pull request per fornire il contesto.

Buon lavoro con i commit!