Senza dubbio l'inizio è il periodo più difficile per gestire con successo un progetto di software libero: la posa di fondamenta solide determinerà se il progetto prospererà o avvizzirà fino a morire. È anche l'argomento di più immediato interesse per chiunque legga questo documento come una guida.
Iniziare un progetto implica un dilemma che come programmatori bisogna affrontare: nessun potenziale utente del programma è interessato ad un programma che non funziona, ma d'altra parte il processo di sviluppo che si vuole impiegare ha come imperativo il coinvolgimento degli utenti.
È in questi pericolosi momenti iniziali che chi si sta dando da fare per iniziare un progetto di software libero deve cercare un equilibrio tra queste esigenze. Uno dei modi più importanti per farlo è stabilire una struttura solida per il processo di sviluppo attraverso alcuni dei suggerimenti delineati in questa sezione.
Se si sta leggendo questo documento, ci sono buone probabilità che si abbia già in mente un'idea per un progetto. Ci sono anche discrete probabilità che questa idea possa soddisfare una lacuna percepita anche da altri, facendo qualcosa che nessun altro progetto di software libero fa, o facendolo in un modo sufficientemente peculiare da necessitare di un nuovo software.
Eric S. Raymond scrive di come nascono i progetti software nel suo nuovo saggio, " The Cathedral and the Bazaar", che è quasi una lettura obbligatoria per ogni sviluppatore di software libero. È disponibile online.
In "The Cathedral and the Bazaar" Raymond dice che: "ogni buon lavoro software comincia grattando il prurito di uno sviluppatore." L'ipotesi di Raymond, ora largamente accettata, è che i nuovi programmi di software libero siano scritti prima di tutto per risolvere un problema specifico presentatosi allo sviluppatore.
Se si ha in mente un'idea per un programma, ci sono buone probabilità che affronti un problema, o "prurito", che ci si vuole grattare: questa idea è il progetto. Esprimerla con chiarezza, scriverla, descrivere in dettaglio il problema che si vuole affrontare: il successo del progetto nel trattare un particolare problema sarà legato all'abilità nell'identificare quel problema con chiarezza fin dall'inizio. Si scopra cosa si vuole che il proprio progetto faccia esattamente.
Monty Manley esprime l'importanza di questo passo iniziale in un saggio, "Managing Projects the Open Source Way." Come mostrerà la prossima sezione, c'è molto lavoro da fare prima ancora che il software sia pronto per essere programmato. Manley dice: "Iniziare come si deve un progetto Open Source significa che uno sviluppatore deve prima di tutto evitare di scrivere codice troppo presto!"
Nel valutare l'idea, bisogna per prima cosa porsi alcune domande. Questo dovrebbe avvenire prima di avanzare ulteriormente nella lettura del presente HOWTO. Ci si chieda: il modello di sviluppo del software libero è davvero quello giusto per il proprio progetto?
Ovviamente, dal momento che il programma gratta un proprio prurito, si è certamente interessati a vederlo implementato in codice. Ma, poiché un singolo hacker che programma in solitudine non si può qualificare come uno sforzo di sviluppo di software open source, ci si deve porre una seconda domanda: qualcun altro potrebbe essere interessato?
Certe volte la risposta è un semplice "no". Se si vuole scrivere un insieme di script per ordinare la propria raccolta di MP3 sulla propria macchina, forse il modello di sviluppo del software libero non è quello giusto. D'altro canto, se si vuole scrivere un insieme di script per ordinare gli MP3 di chiunque, un progetto di software libero potrebbe utilmente riempire un vuoto.
Fortunatamente Internet è un luogo così grande e variegato che è possibile che qualcuno, da qualche parte, condivida i propri interessi e provi lo stesso "prurito". E il fatto che ci siano così tante persone con bisogni e desideri così simili tra loro introduce la terza domanda principale: qualcuno ha già avuto la propria idea, o un'idea abbastanza simile?
Ci sono posti dove si può andare, sul web, per cercare di rispondere alla domanda di cui sopra. Se si ha esperienza con la comunità del software libero probabilmente si ha già familiarità con molti di questi siti. Tutte le risorse elencate sotto consentono di effettuare ricerche nei propri database:
freshmeat.net si autodefinisce come "il più grande indice sul Web per software Linux e Open Source" e la sua reputazione al riguardo è ineguagliabile e indiscussa. Se non si riesce a trovare qualcosa su freshmeat, è difficile che lo si possa trovare altrove.
Slashdot fornisce "Notizie per nerd. Roba che conta", il che di solito comprende discussioni sul software libero, l'open source, la tecnologia, e notizie ed eventi sulla cultura geek. Non è insolito che un progetto di sviluppo particolarmente allettante venga annunciato qui, perciò vale indubbiamente la pena di controllare.
SourceForge ospita e promuove un numero crescente di progetti open source e di software libero. Sta anche rapidamente diventando un punto di incontro ed una sosta obbligata per gli sviluppatori di software libero. La sua mappa dei software e le pagine dei nuovi rilasci dovrebbero essere soste obbligate prima di imbarcarsi in un nuovo progetto software. SourceForge fornisce anche una biblioteca di frammenti di codice che contiene utili pezzetti di codice riusabili, in tutta una gamma di linguaggi, che possono tornare utili in qualsiasi progetto.
Google e la Linux Search di Google offrono potenti strumenti di ricerca del web che possono far scoprire persone che lavorano su progetti simili. Non è un catalogo di software o informazioni come freshmeat o Slashdot, ma vale la pena di controllare, per assicurarsi di non dirigere i propri sforzi verso un progetto ridondante.
Una volta che si è mappata con successo la zona delle operazioni, e si ha un'idea di quali progetti di software libero somiglianti esistono, ogni sviluppatore deve decidere se andare avanti con il proprio progetto. È raro che un nuovo progetto cerchi di raggiungere un obiettivo che non è affatto simile o collegato all'obiettivo di un altro progetto. Chiunque cominci un nuovo progetto deve chiedersi: "il nuovo progetto duplicherà il lavoro fatto da un altro progetto? il nuovo progetto si procaccerà sviluppatori ai danni di un progetto esistente? gli obiettivi del nuovo progetto possono essere raggiunti aggiungendo funzionalità ad un progetto esistente?"
Se la risposta ad almeno una di queste domande è "sì", si provi a contattare lo sviluppatore del progetto (o dei progetti) esistente in questione per capire se lui o lei sarebbe disposto a collaborare.
Per molti sviluppatori questo è l'aspetto più ostico della gestione dei progetti di software libero, ma è un aspetto essenziale: è facile appassionarsi ad un'idea e lasciarsi prendere dall'impeto e dall'eccitazione di un nuovo progetto. Spesso è estremamente difficile da fare, ma è importante che ogni sviluppatore di software libero ricordi che l'interesse della comunità del software libero, e il modo più veloce per raggiungere gli obiettivi del proprio progetto e di progetti simili, spesso può consistere nel non dare il via ad un nuovo processo di sviluppo.
Anche se ci sono un sacco di progetti che falliscono pur avendo nomi descrittivi, e un sacco che hanno successo pur senza averli, quando si dà un nome al progetto vale la pena di pensarci un po' sopra. Leslie Orchard affronta questo problema in un articolo pubblicato su Advogato. L'articolo è breve e sicuramente merita almeno un'occhiata.
Il riassunto è che Orchard raccomanda di scegliere un nome tale che, dopo averlo udito, molti utenti o sviluppatori:
sapranno cosa fa il progetto
se ne ricorderanno un domani
Curiosamente il progetto di Orchard, "Iajitsu," non fa nessuna delle due cose. Probabilmente non c'è alcuna correlazione col fatto che lo sviluppo di quel progetto si è arrestato da quando l'articolo è stato scritto.
Comunque l'argomento è convincente. Ci sono aziende il cui solo lavoro consiste nell'inventare nomi per dei software. Tirano su una quantità di denaro incredibile facendolo, ed è opinione comune che valgano tutto questo denaro. Anche se probabilmente non ci si può permettere un'azienda come questa, ci si può permettere di trarre un insegnamento dalla loro esistenza, e riflettere un momento sul nome che si sta dando al proprio progetto, perché conta.
Se c'è un nome che sta a cuore, ma che non rispetta i criteri di Orchard, si può continuare comunque. Penso che "gnubile" fosse uno dei migliori nomi che abbia mai sentito per un progetto di software libero, e ancora ne parlo, nonostante sia trascorso molto tempo da quando ho smesso di usare il programma. Comunque, se si è flessibili su questo argomento, si ascolti il consiglio di Orchard. Potrebbe aiutare.
Ad un certo livello (piuttosto semplicistico), la differenza tra un software libero ed un software proprietario è la licenza. Una licenza aiuta come sviluppatori proteggendo i propri diritti legali ad ottenere la distribuzione del proprio software alle proprie condizioni, ed incoraggia coloro che vorrebbero aiutare il proprio progetto a partecipare.
Qualsiasi discussione sulle diverse licenze genera sicuramente almeno una piccola flame war, poiché ci sono forti convinzioni che alcune licenze di software libero siano migliori di altre. Questa discussione porta anche alla ribalta la questione del "software open source" e il dibattito sui termini "software open source" e "software libero". Ad ogni buon conto, poiché ho scritto un HOWTO sulla gestione dei progetti di software libero, e non un HOWTO sulla gestione dei progetti software open source, la mia scelta di campo è chiara.
Nel tentativo di raggiungere un diplomatico compromesso, senza sacrificare la mia personale filosofia, consiglio di scegliere una qualsiasi licenza che si conformi alle Debian Free Software Guidelines. Scritte originariamente dal progetto Debian sotto la guida di Bruce Perens, le DFSG costituiscono la prima versione della definizione di Open Source. Esempi di licenze libere forniti dalle DFSG sono la GPL, la BSD, e la Licenza Artistica. Come accennato nell'HOWTO[ESRHOWTO] di ESR, se possibile evitare di scrivere una propria licenza. Le tre licenze citate hanno tutte lunghe tradizioni interpretative. Sono anche senza dubbio software libero (e possono quindi essere distribuite come parte di Debian, e in altri posti che consentono lo scambio di software libero).
Conformemente alla definizione di software libero fornita da Richard Stallman in "The Free Software Definition", ognuna di queste licenze garantisce "la libertà per gli utenti di eseguire, copiare, distribuire, esaminare, modificare e migliorare il software". Ci sono un sacco di altre licenze che si conformano alle DFSG, ma rifarsi ad una licenza più diffusa offrirà il vantaggio di un immediato riconoscimento e comprensione. Molte persone scrivono tre o quattro frasi in un file COPYING e ritengono di aver scritto una licenza di software libero: come prova la mia lunga esperienza con la mailing list debian-legal molto spesso non è così.
Tentando un'analisi più approfondita, sono d'accordo con Karl Fogel che divide le licenze in due gruppi: le GPL, e quelle diverse dalla GPL.
Personalmente, licenzio tutto il mio software sotto la GPL. Creata e difesa dalla Free Software Foundation e dal GNU Project, la GPL è la licenza usata dal kernel Linux, da GNOME, da Emacs, e dalla gran parte del software GNU/Linux. È la scelta naturale, ed io penso che sia una buona scelta. Ogni fanatico BSD ci tiene a ricordare che la peculiare contagiosità della GPL impedisce la mescolanza di codice GPL con codice non-GPL; secondo molte persone (me compreso) questo è un beneficio, ma secondo alcuni è un grosso svantaggio.
Molte persone scrivono tre o quattro frasi in un file COPYING e ritengono di aver scritto una licenza di software libero: come prova la mia lunga esperienza con la mailing list debian-legal, molto spesso non è così. Può non proteggere l'autore, può non proteggere il software, e può rendere le cose molto difficili per chi voglia usare il software ma presta molta attenzione ai sottili dettagli legali delle licenze. Se ci si tiene molto ad una licenza fatta in casa, la si passi prima a qualcuno all'OSI o alla mailing list debian-legal, prima di tutto per proteggersi da imprevisti effetti collaterali.
Le tre licenze più importanti si possono trovare ai seguenti siti:
In ogni caso, si legga ogni licenza prima di usarla per rilasciare il proprio software. Come sviluppatori principali, non ci si possono permettere sorprese sulle licenze.
Il testo della GPL offre una buona descrizione della meccanica di applicazione di una licenza ad un nuovo software. La mia lista di controllo rapido per l'applicazione di una licenza comprende:
rendere se stessi o la FSF il detentore del copyright per il lavoro. In qualche raro caso, si potrebbe desiderare che il detentore del copyright sia qualche organizzazione sponsorizzatrice (se è sufficientemente grande e potente). Fare questo è semplice, basta inserirne il nome nello spazio apposito quando si modifica la nota sul copyright riportata sotto. Contrariamente a quanto comunemente si crede, non c'è bisogno di affiliarsi ad alcuna organizzazione: la nota da sola è sufficiente per rivendicare il diritto d'autore sul proprio lavoro;
se mai fosse possibile, attaccare e distribuire una copia completa della licenza sia con i sorgenti che con i binari, aggiungendo un file a se stante;
in cima ad ogni file sorgente del proprio programma inserire una nota di copyright, ed includere informazioni su dove può essere reperita la licenza integrale. La GPL raccomanda che ogni file cominci con:
una riga per specificare il nome del programma e dare un'idea di cosa fa.
Copyright (C) yyyy nome dell'autore
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
La GPL prosegue raccomandando di aggiungere indicazioni su come contattare l'autore, via email o posta;
la GPL continua consigliando, se il programma viene eseguito in modalità interattiva, di far sì che ogni volta che entra in tale modalità stampi una nota che includa un messaggio come il seguente, che indirizza alle informazioni complete sulla licenza del programma:
Gnomovision version 69, Copyright (C) anno nome dell'autore
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
type `show w'. This is free software, and you are welcome
to redistribute it under certain conditions; type `show c'
for details.
infine, può essere utile includere una "copyright disclaimer" da parte del datore di lavoro o di una scuola, se si lavora come programmatori o se è verosimile che il proprio datore di lavoro, o scuola, possa in futuro accampare diritti di proprietà sul proprio codice. Non ce n'è bisogno frequentemente, ma ci sono molti sviluppatori di software libero che sono finiti nei guai, e vorrebbero avere chiesto una rinuncia di questo genere.
Per favore, per favore, per favore, porre il proprio software sotto il riparo di qualche licenza. Può non sembrare importante, e per voi può non esserlo, ma le licenze sono importanti. Perché un pacchetto software sia incluso nella distribuzione GNU/Linux Debian, deve avere una licenza che soddisfi le linee guida per il software libero di Debian: se il proprio software non ha licenza, non potrà essere distribuito come pacchetto Debian fino a che non sarà ri-rilasciato sotto una licenza libera. Rilasciare la prima versione del proprio software sotto una licenza chiara risparmierà a tutti una seccatura.
La cosa più importante per un sistema di numerazione delle versioni è che ce ne sia uno. Può sembrare pedante enfatizzare questo punto, ma è sorprendente il numero di scripts e piccoli programmi che saltano fuori senza alcun numero di versione.
La seconda cosa più importante per un sistema di numerazione è che i numeri aumentino sempre. I sistemi di tracciamento automatico delle versioni, e la percezione comune di un ordine universale, finirebbero in pezzi se i numeri di versione non crescessero sempre. Non è molto importante che 2.1 sia un grande salto e 2.0.005 un piccolo salto, ma è importante che 2.1 sia più recente di 2.0.005.
Seguendo queste due semplici regole non si sbaglierà (troppo). Oltre a questo, la tecnica più comune sembra essere lo schema di numerazione delle versioni "livello principale", "livello secondario", "livello di patch". Che si sia familiari o meno con questo nome, ci si interagisce di continuo. Il primo numero è il numero principale, e indica importanti cambiamenti o riscritture; il secondo numero è il numero secondario, e rappresenta funzionalità aggiunte o ritoccate basate su una struttura in gran parte coerente; il terzo numero è il numero di patch, e di solito si riferisce solo a rilasci che correggono dei bug.
L'uso molto diffuso di questo schema è il motivo per cui si conoscono la natura e il grado relativo delle differenze tra un rilascio 2.4.12 del kernel Linux ed un 2.4.11, 2.2.12, e 1.2.12, pur senza conoscere nulla su nessuno di questi rilasci.
Si possono modificare o ignorare queste regole, e c'è chi lo fa. Ma attenzione, se si sceglie di farlo, qualcuno si arrabbierà, immaginerà che non le conosciate, e tenterà di insegnarvele, probabilmente non molto gentilmente. Io uso sempre questo metodo, e prego anche voi di farlo.
Ci sono diversi sistemi di numerazione delle versioni piuttosto conosciuti, e che potrebbe valere la pena di investigare prima di rilasciare la propria prima versione.
Il kernel di Linux adotta un sistema di numerazione delle versioni in cui ogni numero di versione minore dispari si riferisce ad un rilascio di sviluppo o di collaudo, ed ogni numero di versione minore pari si riferisce ad una versione stabile. Pensandoci per un secondo, con questo sistema, i kernel 2.1 e 2.3 erano e saranno sempre kernel di sviluppo o di collaudo, mentre i kernel 2.0, 2.2 e 2.4 sono tutti codice di produzione, con maggior grado di stabilità e più collaudati.
Sia che si preveda di avere un modello di sviluppo suddiviso (come descritto nel la Sezione 3.3), sia che si preveda di rilasciare una sola versione alla volta, la mia esperienza con diversi progetti di software libero e con il progetto Debian mi ha insegnato che l'uso del sistema di numerazione delle versioni di Linux merita di essere preso in considerazione. In Debian, tutte le versioni secondarie sono distribuzioni stabili (2.0, 2.1, etc). Ciononostante, molta gente crede che la versione 2.1 sia instabile o di sviluppo, e continua ad usare una versione più vecchia fino a che è così frustrata dalla mancanza di progressi nello sviluppo che protesta, e capisce il sistema. Se non si rilascia mai un numero di versione secondaria dispari ma solo quelli pari, nessuno viene danneggiato, e meno persone saranno confuse: è un'idea che merita di essere presa in considerazione.
A causa della natura insolita dello sviluppo di Wine, per cui il non-emulatore migliora costantemente, ma non si dirige verso un obiettivo immediatamente raggiungibile, Wine è rilasciato ogni tre settimane. Questo viene fatto etichettando i rilasci in un formato "Anno Mese Giorno", in cui ogni rilascio sarà etichettato "wine-XXXXXXXX", cioè la versione del 4 Gennaio 2000 sarebbe "wine-20000104". Per certi progetti, il formato "Anno Mese Giorno" può avere molto senso.
Se si considerano Netscape 6 e le sue versioni commerciali, si nota che la struttura degli sviluppi del progetto Mozilla è uno dei modelli di software libero più complicati in circolazione. La numerazione delle versioni riflette la situazione, unica nel suo genere, in cui questo progetto viene sviluppato.
La struttura dei numeri di versione di Mozilla storicamente è stata composta di pietre miliari. Sin dall'inizio del progetto Mozilla, gli obiettivi del progetto, nell'ordine e nella misura in cui li si sarebbe dovuti raggiungere, erano tracciati su una serie di road map; i punti ed i risultati principali lungo queste road-map erano contrassegnati come pietre miliari. Quindi, anche se Mozilla era compilato e distribuito ogni sera come "nightly build", nel giorno in cui gli obiettivi di una pietra miliare erano stati raggiunti, quella particolare build era contrassegnata come "release milestone".
Anche se non ho visto impiegare questo metodo in nessun altro progetto sinora, l'idea mi piace, e penso che sia valida per i rami di collaudo o di sviluppo di una grande applicazione con una intensa attività di sviluppo.
Un numero enorme di applicazioni altrimenti fantastiche è avvizzito e morto perché il loro autore era la sola persona che sapesse usarle appieno. Anche se il proprio programma è scritto principalmente per un gruppo di utenti tecnologicamente preparati, la documentazione è di aiuto, e finanche necessaria, per la sopravvivenza del progetto. Si imparerà più avanti, nel la Sezione 4.3, che bisogna sempre rilasciare qualcosa di utilizzabile. Un software privo di documentazione non è utilizzabile.
La documentazione deve essere scritta per un pubblico molto vario, e ci sono molti modi per documentare un progetto. L'importanza della documentazione all'interno del codice per facilitare lo sviluppo da parte di una comunità estesa è vitale, ma esula dagli intenti di questo HOWTO. Stando così le cose, questa sezione tratta tecniche utili per la documentazione rivolta agli utenti finali.
Un sistema semi-ufficiale di documentazione, valido per la maggior parte dei progetti di software libero, e che vale la pena di seguire, è il risultato finale di una combinazione di tradizione e necessità. Sia gli utenti che gli sviluppatori si aspettano di poter ottenere documentazione in diversi modi, e se si vuole far decollare il progetto è essenziale fornire, in una forma leggibile, le informazioni che stanno cercando. La gente si aspetta di trovare:
Gli utenti vorrano poter digitare "man nomedelprogetto" ed ottenere una pagina di manuale gradevolmente impaginata che illustri le basi dell'uso dell' applicazione. Ci si assicuri, prima di rilasciare il programma, di averci pensato.
Non è difficile scrivere le pagine di manuale. Eccellente documentazione sul processo di scrittura delle pagine di manuale è disponibile nel "Linux Man-Page-HOWTO", accessibile tramite il progetto Linux Documentation (LDP) e scritto da Jens Schweikhardt. È reperibile dal suo sito o presso (LDP).
È anche possibile scrivere pagine man usando l'SGML di DocBook. Poiché le pagine man sono così semplici, e la metodologia DocBook relativamente nuova, non ho avuto modo di seguire l'argomento, ma sarei felice di ricevere aiuto da chiunque possa darmi ulteriori informazioni sulla cosa.
La maggior parte degli utenti si aspetta che una quantità minima di documentazione sia facilmente disponibile dalla linea di comando. Questo tipo di documentazione dovrebbe difficlmente superare una schermata (24 o 25 righe), ma dovrebbe coprire l'uso di base, una breve descrizione del programma (una o due frasi), una lista dei comandi con spiegazione, e tutte le opzioni principali (anche queste con spiegazione), più un riferimento a documentazione più approfondita per chi ne avesse bisogno. La documentazione a linea di comando per il programma Debian apt-get fornisce un ottimo esempio e un utile modello:
apt 0.3.19 for i386 compiled on May 12 2000 21:17:27
Usage: apt-get [options] command
apt-get [options] install pkg1 [pkg2 ...]
apt-get is a simple command line interface for downloading and
installing packages. The most frequently used commands are update
and install.
Commands:
update - Retrieve new lists of packages
upgrade - Perform an upgrade
install - Install new packages (pkg is libc6 not libc6.deb)
remove - Remove packages
source - Download source archives
dist-upgrade - Distribution upgrade, see apt-get(8)
dselect-upgrade - Follow dselect selections
clean - Erase downloaded archive files
autoclean - Erase old downloaded archive files
check - Verify that there are no broken dependencies
Options:
-h This help text.
-q Loggable output - no progress indicator
-qq No output except for errors
-d Download only - do NOT install or unpack archives
-s No-act. Perform ordering simulation
-y Assume Yes to all queries and do not prompt
-f Attempt to continue if the integrity check fails
-m Attempt to continue if archives are unlocatable
-u Show a list of upgraded packages as well
-b Build the source package after fetching it
-c=? Read this configuration file
-o=? Set an arbitary configuration option, eg -o dir::cache=/tmp
See the apt-get(8), sources.list(5) and apt.conf(5) manual
pages for more information and options.
È diventata una convenzione GNU quella di rendere accessibili queste informazioni con le opzioni "-h" e "--help". La maggior parte degli utenti GNU/Linux si aspetterà di poter recuperare in questo modo la documentazione di base, perciò se si sceglie di usare metodi diversi ci si prepari alle polemiche e alle conseguenze che ne possono derivare.
In aggiunta alle pagine man e all'help a linea di comando, ci sono dei file che chi è in cerca di documentazione controllerà, specialmente nei pacchetti che contengono codice sorgente. In una distribuzione di sorgenti, la maggior parte di questi file può essere conservata nella directory radice della distribuzione, o in una sotto-directory chiamata "doc" o "Documentation". File comunemente in queste posizioni sono:
Un documento che contiene tutte le istruzioni di base per l'installazione, la compilazione, ed anche l'uso: l'insieme minimo di informazioni necessarie per far funzionare il programma. Un README non è l'occasione giusta per essere prolissi, dovrebbe essere conciso ed efficace. Un README ideale è lungo almeno 30 righe, e non più di 250.
Il file INSTALL dovrebbe essere molto più breve del README, e dovrebbe descrivere brevemente e con rapidità come compilare e installare il programma. Di solito un file di INSTALL dice semplicemente all'utente di lanciare "./configure; make; make install", ed accenna a eventuali opzioni o azioni insolite che possono rendersi necessarie. Per la maggior parte delle procedure di installazione relativamente standard, e per la maggior parte dei programmi, i file INSTALL sono il più brevi possibile: raramente superano le 100 righe.
Un CHANGELOG è un file semplice che ogni progetto di software libero ben gestito dovrebbe includere. Un CHANGELOG non è altro che il file che, come suggerisce il nome, registra o documenta i cambiamenti che vengono fatti ad un programma. Il modo più semplice di tenere un CHANGELOG è semplicemente conservare tale file insieme al codice sorgente del programma, e a ogni rilascio aggiungervi in cima una sezione che descrive cosa è stato cambiato, corretto, o aggiunto, al programma. È una buona idea pubblicare il CHANGELOG anche sul sito web, perché può aiutare la gente a capire se vogliono o è necessario aggiornarsi ad una versione più recente, o se invece è meglio aspettare dei miglioramenti più significativi.
Un file NEWS e un ChangeLog si assomigliano, ma diversamente da un CHANGELOG, un file NEWS non è solitamente aggiornato in occasione di nuove versioni: ogni qualvolta si aggiungono nuove funzionalità, lo sviluppatore responsabile lo annoterà sul file NEWS. I file NEWS non dovrebbero essere cambiati prima di un rilascio (dovrebbero essere mantenuti aggiornati di continuo), ma di solito è una buona idea controllare in ogni caso perché spesso gli sviluppatori semplicemente dimenticano di mantenerli aggiornati.
Per i pochi che ancora non lo sanno, FAQ sta per Frequently Asked Questions (domande frequenti), e una FAQ per l'appunto è una loro raccolta. Non è difficile costruire un file di FAQ: semplicemente si stabilisca una prassi per cui se viene posta una domanda, o si legge una domanda su una mailing list, più di una volta, la domanda (e la relativa risposta) verrà aggiunta alle FAQ. Le FAQ sono meno indispensabili dei file elencati sopra, ma possono far risparmiare tempo, migliorare l'usabilità, e diminuire il mal di testa a tutti quanti.
È solo indirettamente una questione di documentazione, ma un buon sito web sta rapidamente diventando una parte essenziale di ogni progetto di software libero. Il sito web dovrebbe fornire accesso alla documentazione (in HTML se possibile); dovrebbe anche includere una sezione per notizie ed eventi relativi al programma, ed una sezione che descriva in dettaglio come partecipare allo sviluppo o al collaudo, invitando esplicitamente alla collaborazione. Dovrebbe anche fornire collegamenti a mailing lists, ad altri siti pertinenti, e fornire un collegamento diretto a tutte le modalità possibili di scaricamento del software.
Tutta la documentazione dovrebbe essere in formato di testo semplice, o, nel caso in cui sia accessibile principalmente dal sito, in HTML: tutti sono in grado di visualizzare un file con cat, tutti sono in grado di visualizzare il testo una pagina per volta, (quasi) tutti sono in grado di leggere documenti HTML. Se si vogliono distribuire informazioni in PDF, PostScript, RTF, o qualsiasi altro formato ampiamente usato, saranno ben accolte, ma queste informazioni devono essere disponibili anche in testo semplice o HTML, altrimenti c'è chi si arrabbierà molto. Secondo me anche info ricade in questa categoria. C'è un sacco di fantastica documentazione GNU che qualcuno semplicemente non legge perché c'è solo sotto forma di info. E questo infastidisce davvero la gente. Non è una questione di formati migliori o peggiori; è una questione di accessibilità, e lo stato di cose attuale è la causa principale di questa intransigenza;
non guasta distribuire tutta la documentazione presente sul sito web (FAQ eccetera) insieme al programma. Non si esiti a buttare tutto quanto nel tarball del programma: se la gente non ne avrà bisogno, lo cancellerà. Continuo a ripeterlo: troppa documentazione non è peccato;
a meno che il software sia valido solo per una lingua diversa dall'inglese (un editor di lingua giapponese, per esempio), per favore lo si distribuisca con documentazione in lingua inglese. Se non si parla l'inglese o comunque non si ha fiducia nel proprio livello di conoscenza, si chieda aiuto ad un amico. Che piaccia o no, giusto o ingiusto che sia, l'inglese è la lingua del software libero. Comunque, questo non vuol dire che la documentazione debba essere limitata all'inglese; chi parla un'altra lingua può distribuire traduzioni della documentazione insieme al software, se ha il tempo e l'energia per farlo. Sicuramente la cosa sarà utile a qualcuno;
infine, per favore controllare l'ortografia della propria documentazione; gli errori ortografici nella documentazione sono dei bug. Io sono tra i primi colpevoli di questo errore, che è estremamente facile da commettere. Se l'inglese non è la propria lingua madre, si faccia controllare o correggere la documentazione e le pagine web da qualcuno di madrelingua inglese: ortografia o grammatica imprecise contribuiscono molto a far apparire il codice poco professionale. Nei commenti al codice queste cose sono meno importanti, ma nelle pagine di manuale e nelle pagine web errori del genere non sono accettabili.
Molti dei restanti problemi legati alla creazione di un nuovo programma di software libero ricadono sotto quello che molta gente chiama buon senso. Si dice spesso che l'ingegneria del software è al 90 per cento buon senso, combinato con il 10 per cento di conoscenze specialistiche; eppure, vale la pena di sottolineare questi problemi, nella speranza che possano far ricordare ad uno sviluppatore qualcosa che aveva dimenticato.
Sono d'accordo con Eric Steven Raymond quando dice che: "è utile a tutti che i file di archivio abbiano dei nomi strutturati come in GNU: una radice alfanumerica tutta minuscola, seguita da un punto, seguito da un numero di versione, da un'estensione, ed altri suffissi." Ci sono altre informazioni (inclusi molti esempi di cosa non fare) nel suo Software Release Practices HOWTO, che è incluso nella bibliografia di questo HOWTO e si può recuperare dal LDP.
I formati dei pacchetti possono differenziarsi a seconda del sistema per cui si sta sviluppando: per software basato su Windows gli archivi zip (.zip) di solito sono il formato eletto; se si sta sviluppando per GNU/Linux, *BSD, o qualche UN*X, ci si assicuri che il codice sorgente sia sempre disponibile in formato tar compresso con gzip (.tar.gz). Il compress di UNIX (.Z) è fuori moda ed inutile; la maggior velocità dei computer ha portato alla ribalta bzip2 (.bz2) come mezzo di compressione più efficace. Ora io rendo disponibili tutti i miei rilasci come tarball compressi sia con gzip che con bzip2.
I pacchetti binari dovrebbero sempre essere specifici per una distribuzione; se si ha la possibilità di compilare pacchetti binari per la versione attuale di una delle distribuzioni principali di Linux, gli utenti ne saranno felici. Si cerchi di promuovere le relazioni con gli utenti o gli sviluppatori di grandi distribuzioni, per sviluppare un sistema per la creazione coerente di pacchetti binari. È spesso una buona idea fornire RPM per RedHat (.rpm), deb per Debian (.deb), e RPM di sorgenti (SRPM) se possibile. Da ricordare: anche se è una cosa gentile fornire questi pacchetti binari, confezionare e rilasciare i sorgenti dovrebbe avere sempre la priorità. Gli utenti o i colleghi sviluppatori possono creare i pacchetti binari, e lo faranno.
Un sistema di controllo di versione può rendere meno problematici molti di questi problemi di confezionamento (e molti altri problemi menzionati in questo HOWTO). Se si sta usando *NIX, CVS è la scelta migliore; vi consiglio di tutto cuore il libro di Karl Fogel sull'argomento (e la versione pubblicata in HTML).
CVS o no, si farebbe probabilmente bene ad investire un po' di tempo per imparare un sistema di controllo di versione, perché fornisce una soluzione automatica per risolvere molti dei problemi descritti in questo HOWTO. Non sono a conoscenza di alcun sistema di controllo di versione libero per Windows o Mac OS, ma so che esistono client CVS per entrambe le piattaforme. Siti web come SourceForge rendono un ottimo servizio, con una interfaccia web per CVS carina e facile da usare.
Vorrei dedicare più spazio in questo HOWTO a CVS, perché mi piace un sacco (lo uso anche per tenere ordine tra le versioni di questo HOWTO!), ma penso che sia al di fuori degli obiettivi di questo documento, e in più ha già i suoi HOWTO dedicati. Il più degno di nota è CVS Best Practices HOWTO [CVSBESTPRACTICES], incluso nella bibliografia allegata.
Altri suggerimenti utili comprendono:
ci si assicuri che il proprio programma sia sempre disponibile nello stesso posto. Spesso questo significa rendere accessibile via FTP o via web una singola directory in cui possa essere velocemente riconosciuta la versione più recente. Una tecnica efficace è fornire un collegamento simbolico chiamato "ilproprioprogetto-latest" che punti sempre alla versione più recente rilasciata, o di sviluppo, della propria applicazione. Si ricordi che questa locazione riceverà molte richieste di download in corrispondenza delle date di rilascio, perciò ci si assicuri che il server scelto abbia una larghezza di banda adeguata;
ci si assicuri che ci sia un indirizzo di email coerente per la segnalazione di bug. Di solito è una buona idea scegliere a questo scopo qualcosa che NON sia il proprio indirizzo di posta elettronica principale, ad esempio ilproprioprogetto@host o ilproprioprogetto-bugs@host. In questo modo, se mai si decidesse di passare in consegna la manutenzione a qualcun altro, o se il proprio indirizzo di posta cambiasse, basterebbe cambiare la destinazione di inoltro di questo indirizzo speciale. Questo permette anche che sia più di una persona a gestire il flusso entrante di posta che si genererà se il progetto diventerà enorme, come si spera.