Conventional Commits e commit semantici

Conventional Commits è una convenzione per scrivere messaggi di commit leggibili da persone e strumenti. Il messaggio comunica il tipo di cambiamento: feature, fix, refactor, test, docs, build.

Non serve solo ordine estetico. Serve a generare changelog, calcolare versioni e rendere la storia filtrabile.

Perché questa lezione conta

Quando il team cresce, i messaggi liberi diventano incoerenti. Uno scrive update, uno fix, uno bugfix, uno correzione. Gli strumenti non possono dedurre significato.

Conventional Commits crea un vocabolario comune.

Obiettivo operativo

Alla fine della lezione devi saper scrivere commit semantici, marcare breaking change e decidere se automatizzare lint e changelog.

Formato

type(scope): description

body opzionale

footer opzionale

Esempi:

feat(auth): aggiungi login con magic link
fix(cart): evita doppio submit checkout
docs(readme): documenta deploy LiteSpeed
test(api): copri timeout provider
refactor(ui): separa componente toolbar

Lo scope è opzionale ma utile. Deve indicare area, non file casuale.

Tipi comuni

feat      nuova funzionalità
fix       correzione bug
docs      documentazione
style     formattazione senza logica
refactor  cambio interno senza comportamento nuovo
test      test
perf      prestazioni
build     build/dependency packaging
ci        pipeline
chore     manutenzione varia
revert    revert di commit

Non moltiplicare tipi senza motivo. Troppi tipi rendono la convenzione meno utile.

Scope e lingua

Lo scope deve aiutare a filtrare la storia:

auth, checkout, api, ui, build, content

Evita scope troppo tecnici se non sono stabili, come il nome di un file destinato a cambiare. Scegli anche la lingua della descrizione. In un team italiano può andare bene l’italiano; in un progetto open source internazionale è più utile l’inglese.

La coerenza conta più della lingua scelta. Commit misti tipo fix, correggo, sistemato, update rendono la storia difficile da leggere e da automatizzare.

Breaking change

Due forme:

feat(api)!: cambia formato risposta utente

oppure:

feat(api): cambia formato risposta utente

BREAKING CHANGE: il campo name viene sostituito da displayName.

Il breaking change deve spiegare impatto e, se possibile, migrazione.

Changelog automatico

Strumenti come release-please, semantic-release o changesets possono leggere i commit e generare changelog.

Esempio di mapping:

fix  -> PATCH
feat -> MINOR
!    -> MAJOR

Non affidarti ciecamente all’automazione se il team non scrive commit bene. Garbage in, garbage out.

Commitlint

Puoi validare:

npm install -D @commitlint/cli @commitlint/config-conventional

Config:

export default {
  extends: ["@commitlint/config-conventional"],
};

Poi hook commit-msg con Husky o lefthook. Valuta però il costo: su team piccoli, una policy nel README può bastare.

Quando non serve

Conventional Commits può essere eccessivo se:

1. progetto personale piccolo;
2. nessun changelog automatico;
3. nessuna release semantica;
4. team non disposto a rispettare la convenzione.

Puoi comunque usare messaggi chiari senza formalismo completo.

Laboratorio guidato

Prendi 15 commit recenti e riscrivili in formato Conventional Commits. Poi genera un changelog manuale:

1. quali sono feature;
2. quali bugfix;
3. quali breaking change;
4. quali non devono comparire in release note.

Se la classificazione è difficile, i commit erano troppo ambigui.

Output atteso

Una policy:

Usiamo Conventional Commits.
Tipi ammessi:
Scope consigliati:
Breaking change:
Strumento di validazione:
Regola per changelog:

Errori comuni

Usare chore per tutto. Perde significato.

Confondere refactor e fix. Se cambia comportamento rotto, è fix.

Segnalare breaking change solo nel testo PR. Deve stare anche nel commit/release.

Automatizzare prima di allineare il team. Prima convenzione, poi tooling.

Checklist di verifica

• so scrivere type(scope): description;
• so marcare breaking change;
• so distinguere feat, fix e refactor;
• so decidere se serve commitlint;
• il changelog generato sarebbe leggibile.

Collegamenti

• Modulo: Workflow di team — lezione 29 del corso.
• La prossima lezione collega commit semantici a tag e versioning.