Da maintainer di codice open source, devo poter scrivere messaggi standardizzati per i commit
ed eseguire lo squash dei feature branch nel master
.
I messaggi dei commit dovrebbero seguire la seguente struttura:
<tipo>[contesto opzionale]: <descrizione>
[corpo opzionale]
[piè di pagina opzionale]
Il commit contiene i seguenti elementi strutturali, allo scopo di comunicarne
l’intento al consumatore della libreria:
fix
risolve un errore nel codice (correlato al PATCH
in un versionamento semver).feat
introduce una nuova funzionalità al codice (correlato al MINOR
in un versionamento semver).BREAKING CHANGE:
all’inizio delle sezioni opzionali corpo o piè di pagina, introduce una breaking API change (correlato al Major
in un versionamento semver).
Una breaking change può essere parte di entrambi i tipi fix:
w feat:
.
feat(parser): add ability to parse arrays
.Sono ammessi altri tipi oltre fix:
e feat:
, ad esempio la convenzione Angular raccomanda docs:
, style:
, refactor:
, perf:
, test:
, chore:
, ma questi non sono coperti da questa specifica.
Nello sviluppo software, secondo la mia esperienza, gli errori sono spesso introdotti ai limiti tra le applicazioni.
I test unitari vanno benissimo per le interazioni che i mantenitori open source conoscono, ma non fanno un ottimo lavoro nel catturare tutti i modi interessanti, spesso inaspettati, con i quali la comunità utilizza una libreria.
Solamente chi ha visto la propria applicazione restituire errori 500 dopo aver aggiornato una dipendenza ad una nuova versione patch, sa quanto sia importante una cronologia di commit facilmente leggibile (e nel migliore dei casi un changlelog ben mantenuto) per il processo di investigazione che dovrà affrontare.
La specifica per commit convenzionali propone l’introduzione di una convenzione facilmente applicabile ai messaggi dei commit. Questa convenzione legata al SemVer, chiede ai sviluppatori software di descrivere nei messaggi dei commit qualsiasi feature, fix e breaking change loro abbiano fatto.
Introducendo questa convenzione, si crea un linguaggio comune che rende più semplice rimuovere errori tra progetti.
Le parole “DEVE”, “NON DEVE”, “RICHIESTO”, “DOVRÀ”, “NON DOVRÀ”, “DOVREBBE”, “NON DOVREBBE”, “RACCOMANDATO”, “POTREBBE” e “OPZIONALE” devo essere interpretata come da specifica RFC 2119.
feat
, fix
, etc.,
seguito dai due punti ed uno spazio.feat
DEVE essere usato quando un commit aggiunge una funzionalità
all’applicazione o libreria.fix
DEVE essere usato quando un commit corregge un errore all’applicazione o libreria.fix(parser):
fixes #13, #5
).BREAKING CHANGE
, seguita dai due punti ed uno spazio.BREAKING CHANGE:
, descrivendo il cambiamento delle API.
Es: BREAKING CHANGE: environment variables now take precedence over config files.feat
e fix
nel messagio.Raccomandiamo di procedere come se il tuo prodotto sia già stato rilasciato. Tipicamente qualcuno, anche i tuoi colleghi, stanno utilizzando il tuo software. Loro vorranno sapere cosa sia stato risolto, cosa si sia rotto etc.
Torna indietro e dividi in più commit dove puoi. Parte del beneficio di usare Commit Convenzionali è quello di spingerti a fare commit e pull request più organizzati.
Disingoraggia farlo in una maniere disorgaizzata. Inoltre ti aiuterà a muoverti più velocemente su più progetti con diversi contributori.
Commit Convenzionali ti incoraggia nel fare più di certi tipi di commit. Inoltre la flessibilità di Commit Convenzionali consente al tuo team di inventare i propri tipi e cambiarli nel tempo.
I commit di tipo fix
dovrebbero essere traducibili ai rilasci PATCH
.
I commit di tipo feat
dovrebbero essere traducibili ai rilasci MINOR
.
I commit con BREAKING CHANGE
, indipentemente dal tipo, dovrebbero essere traducibili ai rilasci MAJOR
.
@jameswomack/conventional-commit-spec
)Raccomandiamo l’utilizzo di SemVer per rilasciare la tua estensione (crea delle estensioni!)
fix
invece di feat
)Se ancora devi creare il merge o il rilascio dell’errore, raccomandiamo l’utilizzo di git rebase -i
per riscrivere la cronologia dei commit.
Nel caso ti abbia già rilasciato questa correzzione dipende dai tool e processi che usi.
feet
invece di feat
)Non è la fine del mondo se un commit non segue la specifica Commit Convenzionali. Semplicemente il commit verrà ignorato dai tool che sono basati su questa specifica.
No. Se usi un workflow basato sugli squash di Git, i mantenitori possono pulire i messaggi dei commit mentre vengono inseriti nel branch principale (merge), non aggiungendo alcun carico di lavoro ai committer occasionali. Un workflow comune è quello di unire (con lo squash) automaticamente i commit dalle pull request e far utilizzare un form ai mantenitori per riscrivere un messaggio più adeguato.
La specifica Commit Convenzionali è ispirata e fortemente basata su Angular Commit Guidelines.
La prima bozza di questa specifica è stata scritta in collaborazione con alcuni contributori di:
vuoi aggingere il tuo progetto alla lista? invia una pull request.