Tenere non solo il codice sorgente del vostro progetto sotto controllo di versione, ma anche le sue pagine web, la documentazione, FAQ, note di progetto, e qualsiasi altra cosa che la gente potrebbe voler modificare. Teneteli vicino al codice sorgente, nello stesso albero di repository. Ogni brandello di informazione che valga la pena scrivere vale la pena mettere sotto controllo—cioè ogni brandello di informazione che potrebbe cambiare. Cose che non cambiano dovrebbero essere archiviate e non messe sotto controllo di versione. Per esempio, le email, quando pubblicate, non cambiano (a meno che diventino parte di un documento più grande e in evoluzione).

La ragione per cui è importante mettere tutto insieme cio che è sotto controllo di versione è che in questo modo la gente deve imparare solo un meccanismo per inviare le modifiche. Qualche volta un contributore inizierà con l'apportare modifiche a pagine web o alla documentazione, spostandosi su piccoli contributi di codice in un secondo momento, per esempio. Quando il progetto usa lo stesso sistema per ogni tipo di contribuzione, la gente deve imparare solo una volta. Inoltre le nuove funzionalità possono essere contribuite insieme con le modifiche alla documentazione, fare il branching del codice farà fare il branch anche alla documentazione eccetera.

Non tenete i file generati(generated files) sotto controllo di versione. Non sono dati veramente editabili, dato che sono generati programmaticamente da altri file. Per esempio, alcuni sistemi di build creano dei configure basati sul template configure.in. Per fare un cambiamento al configure, bisognerebbe cambiare il configure.in e poi rigenerare; quindi solo il template configure.in è un "file editabile". Mettete sotto controllo di versione solo i template—se lo fate anche con i file generati, la gente si dimenticherà inevitabilmente di rigenerare quando fanno il commit di una modifica al template, e le inconsistenze risultanti causeranno confusione a non finire.^[16]

La regola che tutti i dati editabili vadano tenuti sotto controllo di versione ha una sfortunata eccezione: il tracciatore dei bug. I database di bug contengono una gran quantità di dati editabili, ma per ragioni tecniche generalmente non possono memorizzare questi dati nel sistema di controllo principale. ( Comunque, alcuni tracciatori hanno funzionalità di versionamento primitive, indipendenti dal repository principale del progetto.)

Il repository del progetto dovrebbe essere navigabile sul web. Questo non significa solo la possibilità di vedere le ultime revisioni dei file del progetto, ma di andare indietro nel tempo e vedere le versioni precedenti, vedere le differenze tra le revisioni, leggere i messaggi di log per le modifiche selezionate eccetera.

La navigabilità è importante perchè è un portale leggero verso i dati del progetto. Se il repository non può essere visto attraverso un browser web, allora qualcuno che vuole esaminare un file particolare (per esempio, per vedere se una certa fix è stata fatta in quel codice) dovrebbe prima installare localmente il software del client del controllo di versione, il che muterebbe la semplice richiesta da un'attività di due minuti in una da mezz'ora o più.

La navigabilità implica anche URL canoniche per vedere le specifiche revisioni dei file, e per vedere le ultime revisioni in ogni momento. Questo può essere molto utile nelle discussioni tecniche o quando si rimanda la gente alla documentazione. Per esempio, invece di dire "Per suggerimenti sul debugging del server. vedi il file www/hacking.html nella tua copia di lavoro," uno può dire "Per suggerimenti sul debugging del server, vedi http://subversion.apache.org/docs/community-guide/," dando una URL che punti sempre all'ultima revisione del file hacking.html. L'URL è meglio perchè è totalmente non ambigua, ed evita la questione sul fatto che il destinatario abbia o meno una copia di lavoro aggiornata.

Alcuni sistemi di controllo di versione includono meccanismi precostitutiti di navigazione del repository, mentre altri si affidano a strumeti di terze parti. Tre di tali strumenti sono ViewCVS (http://viewcvs.sourceforge.net/), CVSWeb (http://www.freebsd.org/projects/cvsweb.html), e WebSVN (http://websvn.tigris.org/). Il primo funziona sia con CVS che con Subversion, il secondo con CVS soltanto, e il terzo solo con Subversion.

Ogni commit sul repository dovrebbe generare un email che mostra chi ha fatto le modifiche, quando, quali file e directory sono cambiati, e come sono cambiate. L'email dovrebbere essere mandata su una speciale mailing list dedicata alle email di commit, separata dalle altre mailing list a cui la gente scrive. Gli sviluppatori e le altre parti interessate dovrebbero essere incoraggiati a sottoscrivere la mailing list dei commit, dato che è il modo più efficace per stare dietro a cosa sta succedendo nel progetto al livello del codice. Oltre dagli ovvi benefici tecnici della revisione di pari (peer review) (see sezione chiamata «Praticare una Visibile Revisione del Codice»), le email di commit aiutano a creare un senso di comunità perchè stabiliscono un ambiente condiviso in cui la gente può reagire agli eventi (i commit) che sanno essere visibili anche ad altri.

Le specifiche su come creare le email di commit cambieranno a seconda della vostra versione di sistema di controllo di versione, ma solitamente c'è uno script o qualcosa di già preparato per farlo. Se state avendo problemi a trovarlo, provate a guardare la documentazione sugli hooks (uncini), in particolare il post-commit hook, detto anche il hook loginfo in CVS. Gli hook post-commit sono strumenti generali per il lancio di attività automatiche in risposta ai commit. L'hook è lanciato da un commit individuale, viene fornito di tutta l'informazione sul commit, ed è poi libero di usare questa informazione per fare qualcosa—per esempio, mandare un'email.

Con sistemi di email di commit pre-confezionata, potreste volere modificare qualcuno dei loro comportamenti di defult:

Gli utenti non esperti del controllo di versione sono a volte un po' spaventati da branch e merge. Questo è probabilmente uno degli effetti secondari della popolarità di CVS: la sua interfaccia per branch e merge è in qualche modo controintuitiva, così molta gente ha imparato ad evitare totalmente queste operazioni.

Se siete tra queste persone, decidetevi ora a sconfiggere ogni paura che possiate avere e prendetevi tempo per imparare come fare branch e merge. Non sono operazioni difficili, una volta che vi siete abituati, e diventano sempre più importanti man mano che il progetto acquista più sviluppatori.

I branch sono preziosi perchè fanno diventare una risorsa scarsa —una stanza di lavoro nel codice del progetto—in una abbondante. Normalmente, tutti gli sviluppatori lavorano assieme nello stesso ambiente, costruendo lo stesso castello. Quando qualcuno vuole aggiungere un nuovo ponte levatoio, ma non può convincere tutti gli altri che sia un miglioramento, fare un branch render possibile spostarsi in un angolo e provare. Se lo sforzo ha successo, può invitare altri sviluppatori ad esaminare il risultato. Se tutti sono d'accordo che il risultato è buono, possono dire al sistema di controll di versione di spostare (merge) il ponte levatoio dal castello branch a quello principale.

E' facile vedere come questa possibilitò aiuti lo sviluppo collaborativo. La gente ha bisogno della libertà di provare nuove cose senza sentirsi come se stessero interferendo con il lavoro degli altri. Altrettanto importante, ci sono volte in cui il codice ha bisogno di essere isolato dalla solita pentola, per fissare un bug o stabilizzare una release (vedi sezione chiamata «Stabilizzare una Release» e sezione chiamata «Avere in Manutenzione più di Una Linea di Release» in Capitolo 7, Confezione, Rilascio, e Sviluppo Quotidiano) senza preoccuparvi del tracciamento di un bersaglio mobile.

Usate liberamente i branch, e incoraggiate gli altri ad usarli. Ma accertatevi anche che un dato branch sia solo attivo soltanto per il tempo necessario. Ogni branch è una piccola falla nell'attenzione della comunità. Anche coloro che non stanno lavorando in un branch mantengono comunque una visione periferica di cosa stia succedendo. Tale visione è sicuramente desiderabile, e le email di commit dovrebbero essere mandate per i commit del branch come per ogni altro commit. Ma i branch non devono diventare un meccanismo per dividere la comunità di sviluppo. Con rare eccezioni, il fine di molti branch dovrebbe essere qiello di fare il merge delle modifiche con il tronco principale e scomparire.

Fare merge ha un importante corollario: non bisogna mai fare commit della stessa modifica due vole. Cioè, una certa modifica deve entrare nel sistema di controllo di versione esattamente una volta sola. La revisione (o insieme di revisioni) in cui la modifica è entrata a fare parte è il suo unico identificatore da ora in poi. Se ha bisogno di essere applicata a branch diversi da quello in cui è entrata, allora dovrebbe essere unita (merge) dal suo punto originale di ingresso a queste altre destinazioni—in maniera opposta al commit di una modifica testualmente identica, che avrebbe lo stesso effetto sul codice, ma renderebbe l'archiviazione e la gestione dei rilasci impossibili.

Gli effetti pratici di questo consiglio cambiano da un sistema di controllo di versione all'altro. In alcuni sistemi, i merge sono eventi speciali, fondamentalmente diversi dai commit, e portano con loro particolari metadati. In altri, i risultati del merge sono committati allo stesso modo delle altre modifiche, tanto che lo strumento principale per distinguere un merge da un modifica è il messaggio di log. Nel messaggio di log di un merge, non ripetete il messaggio log della modifica originale. Invece, indicate solo che questo è un merge, e fornite la revisione che identifica la modifica originale, con al massimo un sommario di una frase sul suo effetto. Se qualcuno vuole vedere il messaggio di log intero, dovrà consultare la revisione originale.

La ragione per cui è importante evitare la ripetizione dei messaggi di log è che questi messaggi sono spesso modificati dopo che il commit è stato fatto. Se il messaggio di log di una modifica è ripetuto ad ogni destinazione di un merge, allora anche se qualcuno modificato il messaggio originale, lascierà tutte le ripetizioni non corrette—il che causerebbe solo confusione strada facendo.

Lo stesso principio vale per il disfacimento di una modifica. Se una modifica viene tolta dal codice, allora il messaggio di log per la revisiona deve solo dire che qualche specifica revisione è stata disfatta, non descrivere i cambi nel codice che risultano dalla revisione, dato che la semantica della modifica può essere ottenuta leggendo il messaggio di log e la modifica originali. Di certo il messaggio di log della revisione deve anche spiegare la ragione per cui la modifica è stata annullta, ma non deve riprendere nulla del messaggio di log originale della modifica. Se possibile, tornate indietro e modificate il messaggio di log originale della modifica per puntualizzare che è stata annullata.

Tutto ciò di cui sopra implicca che dovreste usare una sintassi consistente per fare riferimento alle revisioni. Ciò è utile non solo nei messaggi di log, ma anche nelle email, nel tracciatore di bug, e da ogni altra parte. Se state usando CVS, suggerisco "path/to/file/in/project/tree:REV", dove REV è il numero di revisione CVS tipo "1.76". Se state usando Subversion, la sintassi standard per la revisione 1729 è "r1729" (i path dei file non sono necessari perchè Subversion usa numeri di revisione globali). In altri sistemi, cìè solitamente una sintassi standard per esprimere il nome degli insiemi di modifiche. Qualunque sia la sintassi appropriata per il vostro sistema, incoraggiate la gente ad usarla quando fa riferimento alle modifiche. Espressioni consistenti di nomi delle modifiche rende la gestione del progetto molto più facile (come vedremo in Capitolo 6, Comunicazione e Capitolo 7, Confezione, Rilascio, e Sviluppo Quotidiano), e dato che buona parte della gestione sarà svolta da volontari, deve essere il più semplice possibile.

Vedi anche sezione chiamata «Le Releases e Lo Sviluppo Quotidiano» in Capitolo 7, Confezione, Rilascio, e Sviluppo Quotidiano.

La maggior parte dei sistemi di controllo di versione offre una funzionalità dove a certe persone può essere permesso o vietato fare il commit in specifiche sotto-aree del repository. Seguendo il principio che quando la gente quando ha un martello in mano, si guarda attorno per cercare i chiodi, molti progetti usano questa opzione senza remore, prudentemente lasciando accesso alla gente solo alle aree in cui un loro commit è approvato, e cercando di essere sicuri che non facciano commit da nessun'altra parte. (Vedi sezione chiamata «Quelli Che Fanno gli Invii» in Capitolo 8, Gestire i Volontari per come i progetti decidono chi può fare commit dove.)

E' probabilmente un po' doloroso esercitare un così stretto controllo, ma una potica più rilassata va anche bene. Alcuni progetti semplicemente usano un sistema d'onore: quando ad una persona viene riconosciuto l'accesso per il commit, anche per sotto-aree del repository, cosa questa veramente riceve è una password che permette di fare commit ovunque nel progetto. Gli è solamente rischiesto di limitare i commit a quell'area. Ricordate che non c'è nessun rischio qui: in un progetto attivo, tutti i commit sono esaminati in ogni caso. Se qualcuno fa un commit che non deve, gli altri lo vedranno e diranno qualcosa. Se una modifica deve essere disfatta,è abbastanza semplice— tutto è comunque sotto controllo di versione quindi basta invertire.

Ci sono diversi vantaggi nell'approccio rilassato. Primo, dato che gli sviluppatori si allargono in altre aree (cosa che solitamente succede se rimangono nel progetto), non c'è nessuno sforzo amministrativo per garantire loro privilegi più ampi. Una volta che la decisione è fatta, la persona deve solo iniziare a fare commit nella nuova area.

Secondo, questo allargamento può essere fatto in modo più fine. Generalmente, uno che fa commit in area X che vuole allargarsi nell'area Y inizierò pubblicando patch su Y e chiedendone revisione. Se qualcuno che già ha l'accesso per fare commit in Y vede la patch e la approva, si può semplicemente dire a chi l'ha sottomessa di fare il commit della modifica direttamente (menzionando il nome di chi l'ha ricevuta/approvata nel messaggio, ovviamente). In questo modo, il commit verrà dalla persona che ha fisicamente scritto la modifica, il che è preferibile sia dal punto di vista di gestione dell'informazione che dal punto di vista del riconoscimento.

Infine, e forse più importante, usare il sistema d'onore incoraggia un'atmosfera di fiducia e mutuo rispetto. Dare a qualcuno l'accesso per il commit in un sottodominio è un'affermazione sulla sua preparazione tecnica—come dire: "Vediamo che hai le conoscenze per fare commit in un certo dominio, quindi fallo". Ma imporre uno stretto controllo di autorizzazione dice: "Non solo stabiliamo un limite alle tue capacità, ma siamo anche un po' sospettosi sulle tue intenzioni." Questo non è il tipo di affermazione che volete fare se potete evitarlo. Portare qualcuno che fa commit nel progetto è un'opportunità per introdurli al circolo della fiducia reciproca. Un buon modo per fare ciò e dare loro più potere di quello che dovrebbero usare, e poi informarli che sta a loro rimanere nei limiti accordati.

Il progetto Subversion ha lavorato con il sistema d'onore per più di quattro anni, con 33 persone che potevano fare commit ovunque e 43 limitatamente. L'unica distinzione che il sistema applicava è tra chi fa commit e chi no; ulteriori sottodivisioni sono mantenute solo dagli umani. Comunque non abbiamo mai avuto un problema con qualcuno che deliberatamente faceva commit fuori dal proprio dominio. Una o due volte ci sono stati degli innocenti equivoci riguardo ai limiti dei privilegi di commit, ma sono sempre stati risolti velocemente e amichevolmente.

Ovviamente in situazioni in cui l'autoregolamentazione non è possibile, dovete affidarvi a severi controlli di autorizzazione. Ma tali situazioni sono rare. Anche quando ci sono milioni di righe di codice e centinaia o migliaia di sviluppatori, un commit su qualunque modulo del codice dovrebbe comunque verificato da chi lavora su quel modulo, e possono riconoscere se qualcuno ha fatto il commit senza esserne autorizzato. Se la regolare revisione dei commit non funziona, allora il progetto ha problemi più grandi da affrontare piuttosto che il sistema di autorizzazione.

Riassumendo, non spendete troppo tempo armeggiando con il sistema di autorizzazione del controllo di versione, a meno che non abbiate delle specifiche ragioni per farlo. Solitamente non poterà molti vantaggi tangibili, mentre invece ci sono vantaggi nell'affidarsi al controllo umano.

Di sicuro niente di ciò vuole dire che le limitazioni in sè non sono importanti. Sarebbe male per un progetto incoraggiare le persone a fare commit in aree in cui non sono qualificate. Inoltre, in molti progetti un accesso pieno (non limitato) ai commit ha uno stato speciale: implica diritti di voto su questioni riguardanti il progetto intero. Questo aspetto politico del commit è discusso sezione chiamata «Chi Vota?» in Capitolo 4, L'Infrastruttura Sociale e Politica.