15. Convenzioni: commit message e versionamento

15.1 Messaggi di commit

Un messaggio di commit può avere più righe: la prima riga fa da “subject”, le successive (dopo una riga vuota) sono il “body”.

Linee guida condivise:

• prima riga breve come riassunto (idealmente ≤ 50 caratteri, comunque meno di 72);
• righe del body limitate a 72 caratteri (comodo per leggere il log nel terminale);
• forma imperativa nella prima riga: “Fix bug”, non “Fixed bug”;
• nel body: il come e il perché della modifica, riferimenti ad altri commit o issue;
• una domanda di controllo utile: “tra 6 mesi riuscirò a capire la modifica leggendo solo il messaggio?”

Conventional Commits (o Semantic Commit) è una convenzione diffusa per rendere la history esplicita e interpretabile da script/automazioni:

<type>[scope opzionale]: <description>

[body opzionale]

[footer opzionali]

Regole principali:

• fix — corregge un bug;
• feat — introduce una nuova funzione;
• altri type comuni: build, chore, ci, docs, style, refactor, perf, test (i team possono definirne di propri);
• i breaking change si segnalano con BREAKING CHANGE: nel footer oppure con ! dopo il type/scope (es. feat!:).

Esempio:

feat(workflows): add commit messages section

More specific info about how to write a commit message and some guidelines.

- basic sane guidelines for commit messages
- reference to conventional commit guidelines

Refs: #2472
Reviewed-by: myself

15.2 Tagging e semantic versioning

I tag indicano tipicamente versioni/rilasci. Per il versionamento, la convenzione più nota è il Semantic Versioning (semver): tre numeri MAJOR.MINOR.PATCH:

• major: incrementa quando il cambio non è retrocompatibile;
• minor: incrementa quando si aggiungono funzioni mantenendo la retrocompatibilità;
• patch: incrementa per correzioni di bug retrocompatibili.

Esempi: 0.2.0 progetto in fase iniziale; 1.0.0 prima versione ufficiale; 1.0.3 terzo fix della 1.0; 1.1.0 nuove funzioni compatibili; 2.0.0 primo rilascio incompatibile; 2.1.0-alpha.1 pre-rilascio.

Convenzione Git consigliata: tag = versione preceduta da v (v1.0.3, v2.1.0-alpha.1, …).

⚠️ I tag contrassegnano snapshot, ma per mantenere due linee di sviluppo (es. supportare la 1.x mentre si sviluppa la 2.x) servono i branch, non i tag.