Una storia di commit fatta di "fix", "wip" e "modifiche varie" non serve a nessuno: non permette di capire perché è cambiato un comportamento, non consente di annullare una singola modifica e rende la revisione una fatica. Git è lo stesso strumento in entrambi i casi: cambia la disciplina con cui lo si usa.
Commit atomici
Un commit contiene una modifica con una sola intenzione, e sta in piedi da solo: il progetto compila e i test passano prima e dopo. Se per descrivere il commit serve la parola "e", sono due commit. Il vantaggio è pratico: si può annullare una modifica senza trascinarne altre, e chi cerca l'origine di un difetto trova una modifica leggibile.
Messaggi che spiegano il perché
La riga di apertura dice che cosa cambia, in modo breve e specifico. Il corpo, quando serve, spiega perché: il problema che si risolve, la scelta fatta, l'alternativa scartata. Il "cosa" lo mostra già la differenza; il "perché" non lo mostra nessuno.
Rami di breve durata
Un ramo vive giorni, non settimane. Più a lungo vive, più si allontana dal ramo principale e più costa riunirlo. Per lavori lunghi si tagliano modifiche piccole che entrano ogni giorno, nascondendo ciò che è incompleto dietro un interruttore di configurazione. Il nome del ramo dice l'intenzione (ad esempio, correzione o funzionalità, più un breve soggetto).
Prima di salvare, guardare
Prima di ogni commit si rilegge la differenza: ci sono righe di debug, file che non c'entrano, segreti? Quello che entra nella storia ci resta. I file generati, le dipendenze scaricate e i segreti non vanno nel repository.
Conflitti
Si risolvono con calma, capendo le due intenzioni, non scegliendo l'uno o l'altro a caso. Dopo la risoluzione si rieseguono i test. Si riallinea il proprio ramo spesso, così i conflitti restano piccoli.
Versioni
Le versioni rilasciate si etichettano con numeri che dicono qualcosa sulla compatibilità (maggiore per le modifiche incompatibili, minore per le aggiunte, patch per le correzioni). L'etichetta si applica dopo che il rilascio è andato a buon fine, non prima.
Lavori in parallelo
Quando più persone o agenti lavorano nello stesso progetto, ciascuno ha il proprio ramo (o una propria copia di lavoro), con compiti che non toccano gli stessi file. Il lavoro parallelo funziona se i confini sono chiari; se due attività toccano gli stessi file, si fanno una dopo l'altra.
Segnali d'allarme
- Commit con messaggi come "fix" o "wip".
- Commit giganti che mescolano più intenzioni.
- Rami vecchi di settimane.
- Segreti o file generati nel repository.
- Conflitti risolti senza riprovare.
- Riscritture della storia già condivisa.
- Grandi modifiche non salvate che si accumulano.
Un esempio
Una correzione tocca tre cose: il calcolo di un totale, il nome di una variabile e un test. In tre commit: "Corregge l'arrotondamento del totale ordine (due punti di arrotondamento)", "Rinomina tot in totale_ordine", "Aggiunge test per ordini con due sconti". Se la correzione causa un problema, si annulla il primo senza perdere gli altri.
Quando usarlo
Ogni volta che si fa una modifica al codice; quando si salva, si crea un ramo, si risolve un conflitto o si organizza il lavoro in più flussi paralleli.
Questo metodo deriva dalla famiglia di skill open source agent-skills di Addy Osmani (licenza MIT), riscritta e adattata.
Questo articolo è una skill di OIAR
Quello che hai letto è il contenuto di una skill del catalogo OIAR, scritto per le persone. Una conoscenza come questa ma più ricca e profonda, scritta per gli agenti, guida le interviste, l'analisi e il report dentro la piattaforma. Le skill si usano in OIAR: per provarla su un tuo progetto serve un account.
git-workflow-and-versioningMetodo per usare git in modo che la storia serva: commit atomici con messaggi che spiegano il perché, rami di breve durata, controllo della differenza prima di salvare, conflitti risolti con test, versioni etichettate, lavoro in parallelo. Usarla ogni volta che si salva una modifica o si organizza il lavoro in rami.