Guide galattiche per aspiranti programmatori

Sebbene nel tempo si siano identificati con “git workflow” una serie di indicazioni relative all’uso di branch e strategie per il merge, non bisogna dimenticare che contribuiscono a un uso produttivo di Git anche strategie e convenzioni legati all’uso dei messaggi di commit e all’uso dei tag per il versionamento. Anche su tale aspetto Git non è prescrittivo, lasciando ai singoli scegliere il modo più adeguato.
 

Messaggi di commit in Git

Per quanto riguarda i messaggi di commit, è importante ricordare che Git permette di inserire un messaggio di commit formato di più righe, usando poi la prima riga del messaggio come “subject” (indicativo da questo punto è la differenza tra git log e git log –oneline).

Un messaggio di commit per l’aggiunta di questa sezione potrebbe essere simile al seguente:

Add commit message section in workflow chapter
More specific info about how to write a commit message and some
guidelines about why it is important to keep them consistent.
We opted to suggest the following:
- use short first line as summary (less than 72 chars, 50 is best)
- wrap body lines to 72 chars (useful to read log on terminal)
- use imperative form for first summary line: "Fix bug", not "Fixed
 bug" or "Fixes bug"
- do the best to format body part to make it readable
- use body part to describe how and why for the commit, as well as
 references to other commits, issues, ...
- think if, in 6 months, you'll be able to understand the change just
 reading the commit message ;-)
Complete and close issue #12

In breve:

• la prima riga del messaggio è la più importante
• le altre righe possono essere usate per chiarire riferimenti, motivazioni e limitazioni legate alle modifiche salvate nel commit, che magari non era necessario o possibile aggiungere direttamente nei file di progetto modificati
• è utile uniformarsi a uno stile comune e coerente per sapere cosa e come trovare informazioni nei messaggi di commit

Una convenzione sui messaggi di commit abbastanza condivisa nel mondo dello sviluppo è quella che prende il nome di Conventional Commit (o Semantic Commit). Questa convenzione indica alcune semplici regole per creare una history dei commit esplicita (che tipo di modifica ho fatto con quel commit?) e interpretabile da script/automatizzazioni.

Un messaggio di commit in linea con la specifica Conventional Commit è strutturato nella seguente forma:

<type>[optional scope]: <description>
[optional body]
[optional footer(s)]

e segue le seguenti regole:

• il <type> deve essere fix per quei commit che correggono un bug
• il <type> deve essere feat se il commit introduce una nuova funzione
• <type> diversi fix e feat sono consentiti, suggerendone alcuni (build, chore, ci, docs, style, refactor, perf, test), ma lasciando anche al team di definirne eventualmente di propri
• se il commit introduce breaking change, questi vanno segnalati iniziando il footer con BREAKING CHANGE: oppure inserendo ! dopo il type/scope nella prima riga.

Se volessimo riscrivere il messaggio di commit d’esempio precedente con queste guideline, potremmo, per esempio, avere qualcosa di simile al seguente:

feat(workflows): add commit messages section
More specific info about how to write a commit message and some
guidelines about why it is important to keep them consistent.
- basic sane guidelines for commit messages
- reference to conventional commit guidelines
Refs: #2472
Reviewed-by: myself

La scelta di scope e delle alte parti opzionali della convezioni sono ovviamente demandate al team, che può regolarsi secondo le proprie necessità.

Per maggiori informazioni rimandiamo al sito ConventionalCommits.