Commit, messaggio e nota tecnica

In parole semplici

Il commit message è il biglietto da visita del fix. Chi lo leggerà tra sei mesi (forse tu) avrà solo quel testo per capire cosa è cambiato e perché. Un buon messaggio descrive il perché, non solo il cosa. Convenzioni semplici (Conventional Commits, regola 50/72) trasformano il git log da elenco di brontolii in cronologia leggibile.

Parole nuove

• Conventional Commits: convenzione che strutturare il messaggio per tipo (fix:, feat:, chore:, …).
• regola 50/72: subject max 50 caratteri, body max 72 colonne per riga.
• breaking change: modifica che rompe la compatibilità.
• scope: contesto della modifica (componente, modulo).

Cosa impari

• Scrivere subject e body chiari.
• Usare Conventional Commits.
• Documentare nel commit ciò che il diff non può dire da solo.

Anatomia del commit message

<tipo>(<scope>): <subject sintetico>  ← max 50 caratteri

<body: cosa cambia, perché, come verificato>  ← max 72 colonne

<footer: refs, breaking change>

Esempio:

fix(carrello): persistere stato dopo update completo

Lo store veniva chiamato prima del dispatch finale, salvando
un payload incompleto. Spostata la chiamata save() dentro
il selector che reagisce allo state aggiornato.

Verificato manualmente con 1, 3 e 50 prodotti.
Aggiunto test E2E playwright/cart-persist.spec.ts.

Refs: #142

Tipi di Conventional Commits

Tipo	Quando usarlo
feat	nuova funzionalità
fix	bug fix
docs	solo documentazione
style	formattazione, niente cambi di logica
refactor	ristrutturazione senza cambi di comportamento
perf	miglioramento di performance
test	aggiunta/correzione test
build	sistema di build, dipendenze
ci	configurazione CI
chore	manutenzione varia
revert	revert di un commit precedente

Lo scope (in parentesi) è facoltativo ma utile: fix(auth), feat(carrello).

La regola 50/72

Storia: i terminali Git mostrano una colonna di max 72 caratteri. GitHub tronca il subject a circa 50. Stare nei limiti rende leggibile il log ovunque.

• Subject (riga 1): max ~50 caratteri. Verbo all’imperativo presente (“aggiungere”, “correggere”), non al passato.
• Riga 2: vuota.
• Body (righe successive): paragrafi separati da riga vuota, ogni riga max 72 colonne.

Cosa scrivere nel body

Tre paragrafi tipici:

1. Cosa fa il commit (sintesi più ampia del subject).
2. Perché (il motivo, il contesto, l’incidente, il bug).
3. Come è stato verificato (test, matrice, percorso manuale).

Cose da non scrivere:

• “fix bug” (vuoto).
• “as discussed” (a chi?).
• “WIP” (allora non committare).
• Smile o emoji eccessivi.
• Dettagli personali (“mentre cenavo”).

Esempio: tre commit per lo stesso bug

Cattivo

fixed cart bug

Mediocre

fix: cart not persisting

Buono

fix(carrello): persistere stato dopo dispatch completo

Il bug compariva perché save() veniva chiamato prima del
dispatch finale, salvando uno stato vuoto. Sposta save()
dentro un selector che reagisce solo allo state aggiornato.

Verificato: carrello 1/3/50 prodotti, logout/login,
storage Application > Local Storage.

Refs: #142

Breaking change

Quando il fix cambia un’API o un contratto, segnalalo nel footer:

fix(api): rinominare campo `userId` in `user_id`

BREAKING CHANGE: tutti i client che leggevano `userId`
devono aggiornarsi a `user_id`. Vedi MIGRATION.md.

Tool come semantic-release o release-please riconoscono BREAKING CHANGE e bumpano la versione major.

Nota di release

Per ogni fix significativo, aggiungi una riga in CHANGELOG.md:

## [2.3.1] - 2026-05-16

### Fixed
- Carrello non persiste dopo update completo (#142).

Il CHANGELOG è la versione pubblica del commit message. Storia leggibile per utenti e team.

Comandi utili

Editor del commit:

git commit              # apre editor
git commit -m "..."     # messaggio inline (sconsigliato per body lunghi)
git commit --amend      # modifica l'ultimo commit (solo se non pushato)

Per messaggi multilinea da CLI senza editor:

git commit -m "fix(carrello): persistere stato dopo dispatch completo" \
           -m "Il bug compariva perché save() veniva chiamato prima..."

Convenzione git log leggibile:

git log --oneline --decorate --graph --all

Esercizio guidato

Riprendi cinque commit recenti dal tuo repo (anche di un tuo progetto personale).

1. Per ciascuno, valuta: subject < 50 caratteri? imperativo? body utile?
2. Riscrivili in formato Conventional Commits.
3. Per uno particolarmente vago, espandi il body con cosa/perché/come.
4. Compara la leggibilità del prima e del dopo.

Se i commit sono già pushati: non riscriverli (sarebbe --force). Applica il formato dai prossimi.

Errori frequenti del principiante

• Subject vago: “update”, “fix”, “stuff”.
• Subject al passato: “fixed”, “added”. Convenzione vuole imperativo presente.
• Body assente: nessun motivo, solo what.
• --amend di commit pushati: riscrive storia condivisa.
• Mai aggiornare il CHANGELOG: il git log lo sa solo lo sviluppatore.