Autore: Marco Cesarato
La modalità di commit di git dovranno seguire un insieme di semplici regole per avere cosi una cronologia di commit esplicita e comprensibile una volta consultata. Inoltre ciò rende più facile utilizzare strumenti per l'automatizzazione di processi per la consultazione o l'auto generazione. Quindi per poter essere analizzati dallo script di auto generazione del changelog (registro modifiche) sarà necessario che i commit seguano esattamente la seguente struttura e le seguenti regole.
Esistono inoltre strumenti per JetBrains, Visual Studio Code e altri editor (i link nella sezione dedicata a fondo pagina) che aiutano alla scrittura di tali commit rispettando le regole convenzionali stabilite.
- Comunicare la natura dei cambiamenti a colleghi, pubblico, o altri parti interessate.
- Rendere più semplice alle persone contribuire al progetto, dando la possibilità di esplorare una cronologia di commit più strutturata.
- Possibilità di attivare build e processi di rilascio.
Esempi:
- Generazione dei CHANGELOG automatica.
- Versionamento automatico
I messaggi dei commit devono seguire la seguente struttura:
<tipo>([contesto opzionale]): <descrizione>
< -- linea vuota -- >
[corpo opzionale]
< -- linea vuota -- >
[piè di pagina opzionale]
Il tipo definisce il contenuto del commit e in maniera generica la motivazione del commit. Ad esso va sempre e comunque associata una descrizione specifica del commit.
I tipi vanno scritti tutti in minuscolo e vanno seguiti dai due punti e uno spazio (esempio "feat: " ).
Alla tipologia può essere aggiunto opzionalmente il contesto del commit, che va aggiunto tra parentesi subito dopo il tipo e prima dei due punti (esempio: "feat(Agenda): ").
Ecco la lista delle tipologie principali utilizzabili:
chore: Cambiamenti che non modificano i file con il codice sorgente (esempio i file di configurazione)feat: Una nuova funzionalità (feature)fix: Un bug fixrefactor: Cambiamenti al codice che non aggiungono nessuna funzionalità e non risolvono nessun bug (esempio ristrutturazione del codice oppure il cambio del nome di una classe/funzione)style: Modifiche che non influiscono sul significato del codice (spazi, formattazione, punti e virgola mancanti, ecc.)revert: Ripristina (revert) un commit precedenteperf: Miglioramento delle performancedocs: Documentazione
Subito dopo la tipologia di commit va inserita una descrizione specifica per il commit che NON deve essere generica ("fix: risoluzione problemi" oppure "feat: aggiunta funzionalità") ma deve spiegare esplicitamente e contenuta (essendo la descrizione, se si ha bisogno di inserire più dettagli è necessario inserirli nel corpo del commit) le modifiche apportate al codice.
Dopo la descrizione seguito da una linea vuota può essere aggiunto opzionalmente il messaggio completo nei dettagli del nostro commit. È possibile anche andare a capo.
Dopo il corpo (o la descrizione se il corpo non e stato inserito) seguito da una linea vuota può essere aggiunto opzionalmente il piè di pagina, dove può essere indicato:
- Risoluzione issue (
Closes) : Il commit specifico risolve la issue indicata (esempio:Closes: #12) e chiude automaticamente la stessa - Breaking change (
BREAKING CHANGE) : Una modifica drastica al codice che rende incompatibili librerie/client che utilizzano classi/funzioni/endpoint (esempio: vengono rinominati e quindi da quel momento in poi non funzionerebbero più con la vecchia metodologia) o vengono aumentati/aggiunti i requisiti minimi del sistema (esempio:BREAKING CHANGE: termine del supporto a NodeJS 12). - Autore Multiplo (
Co-authored-by) : Il commit è co-autore di un'altra persona (per più persone utilizzare una riga ciascuna) (esempio:Co-authored-by: marcoce) - Implementazione (
Implements) : Il commit implementa una feature (esempio:Implements: hooks)
Mettiamo assieme tutti i concetti illustrati e vediamo assieme qualche esempio.
-
Rilascio nuova release
chore(release): 1.30 -
Aggiunta nuovo modulo
feat: creato nuovo modulo agenda -
Risoluzione problema
fix(Agenda): risolto loop infinito nella decodifica dei datiNB: Inserito subito dopo il tipo possiamo notare che tra le parentesi è presente anche il contesto del commit
-
Aggiunta documentazione
docs: aggiunta nuova sezione nel readme -
Messaggio di un commit per un fix utilizzando il numero della issue (opzionale)
fix: risoluzione problema che impediva la visualizzazione dei dati
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt
ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Closes: #12
- Messaggio di un commit con una breaking change
chore: termine supporto a NodeJS 12
BREAKING CHANGE: termine del supporto a NodeJS 12
oppure semplificando con il simbolo !:
chore!: termine supporto a NodeJS 12
| Tipo | Nome | Descrizione |
|---|---|---|
| feat | Feature | Una nuova funzionalità |
| fix | Correzioni di bug | Una correzione di bug |
| docs | Documentazione | Aggiunte e modifiche alla documentazione |
| style | Stili | Modifiche che non influiscono sul significato del codice (spazi, formattazione, punti e virgola mancanti, ecc.) |
| refactor | Refactoring del codice | Cambiamenti al codice che non aggiungono né funzionalità e né risolvono alcun bug (esempio il cambio del nome di una classe o funzione) |
| perf | Miglioramenti delle prestazioni | Una modifica del codice che migliora le prestazioni |
| test | Test | Aggiunta di test mancanti o correzione di test esistenti |
| build | Build | Modifiche che influenzano il sistema di compilazione o le dipendenze esterne (ambiti di esempio: gulp, broccoli, npm) |
| ci | Continuos Integration | Modifiche ai nostri file e script di configurazione CI (ambiti di esempio: Travis, Circle, BrowserStack, SauceLabs) |
| chore | Altro | Altre modifiche che non modificano il codice sorgente o file di test (esempio i file di configurazione) |
| revert | Ripristina | Ripristina un commit precedente |