  Software Release Practice HOWTO
  Eric S. Raymond <esr@thyrsus.com>
  1.0, 21 novembre 1998

  Questo HOWTO descrive le regole di una buona release per un progetto
  open-source per Linux. Seguendo queste regole, si faciliter il pi
  possibile gli utenti nel costruire il codice e usarlo, e gli altri
  sviluppatori nel capirlo e cooperare per migliorarlo.  Questo docu
  mento  una lettura obbligata per i novelli sviluppatori. Gli svilup
  patori esperti devono fare una revisione quando stanno rilasciando un
  nuovo progetto. Verr riveduto periodicamente per mostrare le
  evoluzioni degli standard.  La traduzione italiana  stata curata da
  Edoardo Rampazzo <Taedium@mclink.it>
  ______________________________________________________________________

  Indice Generale


  1. Introduzione
     1.1 Perch questo documento?
     1.2 Nuove versioni di questo documento

  2. Buone regole per dare un nome a un progetto e a un archivio
     2.1 Usare nomi nello stile GNU, con una radice e numerazione delle patch primarie.secondarie
     2.2 Scegliere con accuratezza un nome per il prefisso che sia unico e facile da digitare

  3. Buone regole di sviluppo
     3.1 Scrivere in puro ANSI C o in un linguaggio portabile
     3.2 Seguire le buone regole della portabilit del linguaggio C
     3.3 Utilizzare autoconf/ automake/ autoheader
     3.4 Controllare lo stato del codice prima di rilasciarlo

  4. Buone regole per creare una distribuzione
     4.1 Essere sicuri che gli archivi tar vengano sempre decompressi in una nuova singola directory
     4.2 Fornire un README
     4.3 Rispettare e seguire le regole standard per la titolazione dei file

  5. Buone regole di comunicazione
     5.1 Riferire a c.o.l.a
     5.2 Riferire ad un newsgroup attinente al tema
     5.3 Fornire un sito Web
     5.4 Creare delle mailing list attinenti al progetto
     5.5 Distribuzione attraverso i pi importanti archivi
     5.6 Fornire archivi RPM


  ______________________________________________________________________

  11..  IInnttrroodduuzziioonnee


  11..11..  PPeerrcchh qquueessttoo ddooccuummeennttoo??

  C' un gran numero di buone regole tradizionali per un codice open-
  source che aiutano gli altri nel portarlo, usarlo e cooperare nel suo
  sviluppo.  Alcune di queste convenzioni sono tradizionali nel mondo
  Unix e nei precursori di Linux; altre sono state sviluppate
  recentemente in risposta a particolari nuovi strumenti e nuove
  tecnologie come il World Wide Web.

  Questo documento aiuter ad acquisire queste regole. Lo stesso 
  organizzato in sezioni, ciascuna contenente un indice degli argomenti.
  Quest'ultimo servir anche come controllo preliminare ai fini della
  distribuzione.


  11..22..  NNuuoovvee vveerrssiioonnii ddii qquueessttoo ddooccuummeennttoo

  Questo documento sar postato mensilmente nel newsgroup
  comp.os.linux.answers . Il documento  archiviato su diversi siti FTP
  riguardanti Linux, incluso sunsite.unc.edu in pub/Linux/docs/HOWTO.

  Si pu prendere visione dell'ultima versione di questo HOWTO sul World
  Wide Web all'URL <http://sunsite.unc.edu/LDP/HOWTO/Software-Release-
  Practice.html>.

  Si  autorizzati a spedire domande o commenti su questo HOWTO a Eric
  S. Raymond, esr@snark.thyrsus.com <mailto:esr@snark.thyrsus.com>.


  22..  BBuuoonnee rreeggoollee ppeerr ddaarree uunn nnoommee aa uunn pprrooggeettttoo ee aa uunn aarrcchhiivviioo

  Poich il carico sui distributori di archivi, come Sunsite, il sito
  del PSA e CPAN,  in aumento, si tende sempre pi a far processare le
  proposte da valutare in parte o completamente da dei programmi
  (piuttosto che interamente da una persona).

  Questo rende pi importante, per un progetto o un nome di un archivio,
  adattare bene i nomi a modelli regolari che il programma possa
  analizzare e capire.


  22..11..  UUssaarree nnoommii nneelllloo ssttiillee GGNNUU,, ccoonn uunnaa rraaddiiccee ee nnuummeerraazziioonnee ddeellllee
  ppaattcchh pprriimmaarriiee..sseeccoonnddaarriiee

   bene che tutti i file dell'archivio abbiano nomi sullo stile GNU:
  radice prefissante in caratteri tutti minuscoli, seguiti da un
  trattino, dal numero della versione, dall'estensione, e da altri
  suffissi.

  Supponiamo che si abbia un progetto di nome `foobar', alla versione 1,
  release 2, livello 3. Se si tratta di un solo archivio
  (presumibilmente i sorgenti), ecco come dovrebbero essere i nomi:


     ffoooobbaarr--11..22..33..ttaarr..ggzz
        L'archivio dei sorgenti


     ffoooobbaarr..llssmm
        Il file LSM (assumendo che si sia sottoposti a Sunsite).


  per favore _n_o_n usare:


     ffoooobbaarr112233..ttaarr..ggzz
        Questo sembrer a molti programmi un archivio di un progetto
        chiamato `foobar123' senza numero della versione.


     ffoooobbaarr11..22..33..ttaarr..ggzz
        Questo sembrer a molti programmi un archivio di un progetto
        chiamato `foobar1' nella versione  2.3.


     ffoooobbaarr--vv11..22..33..ttaarr..ggzz
        Molti programmi lo interpreterebbero come un progetto chiamato
        `foobar-v1'.



     ffoooo__bbaarr--11..22..33..ttaarr..ggzz
        La sottolineatura  difficile da leggere, scrivere e ricordare


     FFooooBBaarr--11..22..33..ttaarr..ggzz
        A meno che non _s_i _v_o_g_l_i_a assomigliare ad una mezza cartuccia del
        marketing.  Inoltre  difficile da leggere, scrivere, e
        ricordare.

  Se si deve distinguere tra archivi di sorgenti e di binari, o tra tipi
  diversi di binari, o esprimere alcuni tipi di opzioni nel nome del
  file, si  pregati di considerarle come un' estensione del file e
  metterle _d_o_p_o il numero della versione.  Cio,  meglio scrivere:


     ffoooobbaarr--11..22..33..ssrrcc..ttaarr..ggzz
        sorgenti


     ffoooobbaarr--11..22..33..bbiinn..ttaarr..ggzz
        binari, di tipo non precisato


     ffoooobbaarr--11..22..33..bbiinn..EELLFF..ttaarr..ggzz
        binari di tipo ELF


     ffoooobbaarr--11..22..33..bbiinn..EELLFF..ssttaattiicc..ttaarr..ggzz
        binari ELF linkati staticamente


     ffoooobbaarr--11..22..33..bbiinn..SSPPAARRCC..ttaarr..ggzz
        binari SPARC

  Si  pregati di _n_o_n usare nomi come `foobar-ELF-1.2.3.tar.gz', perch
  i programmi hanno difficolt a distingure i suffissi (come `-ELF')
  dalla radice del nome.

  Un buon modello generale per un nome  costituito, nell'ordine, da:


  1. prefisso del progetto

  2. trattino

  3. numero della versione

  4. punto

  5. "src" o "bin" (facoltativo)

  6. punto o trattino (meglio un punto)

  7. tipologia del binario e opzioni (facoltativo)

  8. estensioni dell'archivio e del tipo di compressione


  22..22..  SScceegglliieerree ccoonn aaccccuurraatteezzzzaa uunn nnoommee ppeerr iill pprreeffiissssoo cchhee ssiiaa uunniiccoo
  ee ffaacciillee ddaa ddiiggiittaarree

  La radice prefissante dovrebbe essere comune a tutti i file di un
  progetto, facile da leggere, scrivere e ricordare.  Si  pregati
  quindi di non usare sottolineature.  Ugualmente non usare caratteri
  maiuscoli e maiuscoletti senza una buona ragione -- confondono
  l'ordine di ricerca dell'occhio umano e ricordano una mezza cartuccia
  del marketing che voglia fare l'intelligente.

  Crea inoltre confusione il fatto che due progetti diversi hanno lo
  stesso nome. Si cerchi cos di controllare eventuali conflitti prima
  di rilasciare la propria nuova release.  Un buon luogo dove
  controllare  costituito dal file di indice di Sunsite
  <http://sunsite.unc.edu/pub/Linux>.


  33..  BBuuoonnee rreeggoollee ddii ssvviilluuppppoo

  La maggior parte di queste regole sono volte ad assicurare la
  portabilit, non solo verso sistemi Linux ma ugualmente verso altri
  sistemi Unix.  Essere portabile verso altri sistemi Unix non  solo un
  segno di professionalit e cortesia del programmatore, ma anche
  un'assicurazione preziosa contro eventuali futuri cambiamenti in Linux
  stesso.

  Inoltre, altre persone _c_e_r_c_h_e_r_a_n_n_o di compilare il loro codice su
  sistemi non-Linux; con la portabilit si ridurr il numero di persone
  perplesse che invieranno fastidiosissime e-mail.


  33..11..  SSccrriivveerree iinn ppuurroo AANNSSII CC oo iinn uunn lliinngguuaaggggiioo ppoorrttaabbiillee

  Per la portabilit e la stabilit, si dovrebbe scrivere in ANSI C o in
  un altro linguaggio che sia garantito come portabile in quanto abbia
  un'implementazione multi-piattaforma.

  Linguaggi di questo tipo includono Python, Perl, Tcl ed Emacs Lisp.
  Vecchi, semplici linguaggi shell non sono qualificati; ci sono troppe
  differenti implementazioni con sottili idiosincrasie, e l'ambiente
  shell  soggetto a interruzioni dovute alle configurazioni dell'utente
  come, ad esempio, quelle degli alias delle shell.

  Java promette bene come linguaggio portabile, ma le implementazioni
  disponibili per Linux sono appena abbozzate e scarsamente integrate
  con Linux. La scelta di Java  per ora il minore dei mali, sebbene
  possa divenire pi popolare con il tempo.



  33..22..  SSeegguuiirree llee bbuuoonnee rreeggoollee ddeellllaa ppoorrttaabbiilliitt ddeell lliinngguuaaggggiioo CC

  Se si scrive in C, si  liberi di usare pienamente le caratteristiche
  ANSI -- prototipi di funzioni inclusi, che aiuteranno a individuare le
  inconsistenze tra i diversi moduli. I compilatori in vecchio stile K&R
  sono superati.

  D'altra parte non si presupponga che alcune caratteristiche specifiche
  del GCC come l'opzione '-pipe' o le funzioni nidificate siano
  disponibili.  Queste si torceranno contro a chiunque faccia un porting
  verso sistemi non-Linux o non-GCC.


  33..33..  UUttiilliizzzzaarree aauuttooccoonnff// aauuttoommaakkee// aauuttoohheeaaddeerr

  Se si scrive in C, usare autoconf/automake/autoheader per risolvere
  problemi di portabilit, sondare la configurazione del sistema, e
  confezionare i makefile. Chi installa dai sorgenti si aspetta,
  giustamente, di poter digitare "configure; make" e ottenere una
  struttura pulita.



  33..44..  CCoonnttrroollllaarree lloo ssttaattoo ddeell ccooddiiccee pprriimmaa ddii rriillaasscciiaarrlloo

  Se si scrive in C, fare un test con '-Wall' ed eliminare gli errori
  almeno una volta prima di ciascuna release. Questo blocca un numero
  sorprendente di errori. Per una totale completezza si compili anche
  con '-pedantic'.

  Se si scrive in Perl, controllare il codice con 'perl -c', 'perl -w',
  e 'perl -T' prima di ciascuna release (si veda la documentazione
  Perl).


  44..  BBuuoonnee rreeggoollee ppeerr ccrreeaarree uunnaa ddiissttrriibbuuzziioonnee

  Le seguenti indicazioni descrivono come la propria distribuzione
  dovrebbe apparire quando qualcuno la rintraccia, la scarica e la
  decomprime.


  44..11..  EEsssseerree ssiiccuurrii cchhee ggllii aarrcchhiivvii ttaarr vveennggaannoo sseemmpprree ddeeccoommpprreessssii iinn
  uunnaa nnuuoovvaa ssiinnggoollaa ddiirreeccttoorryy

  Il pi fastidioso errore dei novelli sviluppatori consiste nel fare
  archivi tar che decomprimono i file e le directory della distribuzione
  nella directory corrente, magari sovrascrivendo file gi esistenti.
  _N_o_n _b_i_s_o_g_n_a _f_a_r_l_o _m_a_i _!

  Invece, si dev'essere sicuri che i file del proprio pacchetto abbiano
  tutti una porzione di directory chiamata come il progetto, affinch
  questi vengano decompressi in una singola directory direttamente _s_o_t_t_o
  quella corrente.

  Ecco un trucco per un makefile che agisce in questo modo, assumendo
  che la directory della propria distribuzione venga chiamata `foobar' e
  che SRC contenga un elenco dei file della distribuzione stessa.  Ci
  richiede GNU tar 1.13



  VERS=1.0
  foobar-$(VERS).tar.gz:
          tar --prefix-name='foobar-$(VERS)/' -czf foobar-$(VERS).tar.gz $(SRC)



  Se si ha un versione pi vecchia di tar, si pu provare una cosa del
  tipo:


  foobar-$(VERS).tar.gz:
          @ls $(SRC) | sed s:^:foobar-$(VERS)/: >MANIFEST
          @(cd ..; ln -s foobar foobar-$(VERS))
          (cd ..; tar -czvf foobar/foobar-$(VERS).tar.gz `cat foobar/MANIFEST`)
          @(cd ..; rm foobar-$(VERS))



  44..22..  FFoorrnniirree uunn RREEAADDMMEE

  Bisogna fornire un file chiamato README o READ.ME che funga da mappa
  per la propria distribuzione. Per una vecchia convenzione, questo  il
  primo file che gli intrepidi esploratori leggeranno dopo aver
  decompresso i sorgenti.


   bene che il README includa:


    Una breve descrizione del progetto.

    Un link al sito web del progetto (se ne ha uno).

    Note sull'ambiente di progettazione ed eventuali problemi di
     portabilit.

    Una mappa che descriva i file importanti e le sotto-directory.

    Istruzioni per l'installazione e la compilazione o un richiamo a un
     file che contenga le stesse (di solito INSTALL).

    Un elenco di coloro che hanno fatto e che mantengono il progetto o
     un richiamo ad un file che lo contenga (di solito CREDITS).

    Novit recenti sul progetto o un richiamo ad un file che contenga
     le stesse (di solito NEWS).


  44..33..  RRiissppeettttaarree ee sseegguuiirree llee rreeggoollee ssttaannddaarrdd ppeerr llaa ttiittoollaazziioonnee ddeeii
  ffiillee

  Prima ancora di leggere il README, l'intrepido esploratore avr
  analizzato i nomi dei file nella directory della distribuzione appena
  decompressa.  Quei nomi possono essi stessi fornire delle
  informazioni. Aderendo a standard fissi sulle regole di nominazione,
  si pu dare all'esploratore degli indizi preziosi su ci che  in
  procinto di guardare.

  Ecco alcuni nomi standard di file e il loro significato. Non  detto
  che siano tutti necessari per tutte le distribuzioni.


     RREEAADDMMEE oorr RREEAADD..MMEE
        Il file della mappa, da leggersi per primo


     IINNSSTTAALLLL
        istruzioni per la configurazione, struttura e l'installazione


     CCRREEDDIITTSS
        elenco di chi ha contribuito al progetto


     NNEEWWSS
        notizie recenti sul progetto


     HHIISSTTOORRYY
        storia del progetto


     CCOOPPYYIINNGG
        termini di licenza del progetto (convenzione GNU)


     LLIICCEENNSSEE
        termini di licenza del progetto


     MMAANNIIFFEESSTT
        elenco dei file della distribuzione
     FFAAQQ
        documento testo contenente le domande poste pi di frequente
        (Frequently Asked Question) sul progetto


     TTAAGGSS
        tag-file generato per uso di Emacs o vi

  N.B. Si accetta come convenzione generale che i nomi dei file scritti
  tutti in caratteri maiuscoli costituiscano matainformazioni leggibili
  sul pacchetto, e non sui suoi componenti.


  55..  BBuuoonnee rreeggoollee ddii ccoommuunniiccaazziioonnee

  Il proprio software non render il mondo migliore se nessuno sa che
  esiste.  Inoltre, con una presenza visibile del progetto su Internet
  sar pi semplice trovare utenti e co-sviluppatori. Ecco i modi
  standard per farlo.


  55..11..  RRiiffeerriirree aa cc..oo..ll..aa

  Annunciare la nuova release a comp.os.linux.announce
  <news:comp.os.linux.announce>.  Oltre a essere letto da moltissime
  persone, questo gruppo  una dei pi grossi contenitori di siti web
  riguardanti le novit del settore, come Freshmeat
  <http://www.freshmeat.net>.


  55..22..  RRiiffeerriirree aadd uunn nneewwssggrroouupp aattttiinneennttee aall tteemmaa

  Si trovi un gruppo USENET attinente alla propria applicazione, e si
  annunci l la sua uscita.  Si posti solo dove la _f_u_n_z_i_o_n_e del codice 
  attinente, e si restringa il campo d'azione.  Se (per esempio) si sta
  rilasciando un programma scritto in Perl che consulti un server IMAP,
  si dovrebbe sicuramente postare a comp.mail.imap. Ma non si dovrebbe
  probabilmente postare a comp.lang.perl a meno che il programma non sia
  anche un esempio istruttivo delle tecniche Perl all'avanguardia.

  L'annuncio dovrebbe includere l'URL di un sito web del progetto.


  55..33..  FFoorrnniirree uunn ssiittoo WWeebb

   importante avere un sito web se si vogliono raccogliere utenti o un
  gruppo di sviluppatori del progetto. Caratteristiche standard di un
  sito sono:

    Lo statuto del progetto (perch esiste, a chi si rivolge, ecc.).

    Collegamenti per scaricare i sorgenti.

    Istruzioni per iscriversi alla/alle mailing list del progetto.

    Un elenco di FAQ (Frequently Asked Questions).

    Documentazione in HTML sul progetto.

    Link a progetti correlati e/o in competizione con il proprio.

  Alcuni siti di progetti forniscono anche degli URL per l'accesso
  anonimo al master source tree.



  55..44..  CCrreeaarree ddeellllee mmaaiilliinngg lliisstt aattttiinneennttii aall pprrooggeettttoo

   una pratica comune creare una lista privata di sviluppo attraverso
  cui i collaboratori del progetto possano comunicare e scambiarsi delle
  patch. Si potrebbe anche creare una lista di annunci e notizie per le
  persone che vogliano essere tenute informate sullo stato del progetto.


  55..55..  DDiissttrriibbuuzziioonnee aattttrraavveerrssoo ii ppii iimmppoorrttaannttii aarrcchhiivvii

  Negli anni scorsi, l'archivio di Sunsite
  <http://www.sunsite/unc.edu/pub/Linux/>  stato il pi importante
  luogo di scambio per i programmi Linux.

  Altri siti importanti sono:


    Il sito del Python Software Activity <http://www.python.org> (per
     programmi scritti in Python).

    Il CPAN <http://language.perl.com/CPAN>, Comprehensive Perl Archive
     Network, (per programmi scritti in Perl).


  55..66..  FFoorrnniirree aarrcchhiivvii RRPPMM

  La configurazione standard de-facto per i pacchetti di binari
  installabili  quella usata dal Red Hat Package Manager, RPM. 
  presente nella maggior parte delle pi conosciute distribuzioni Linux,
  e supportato efficacemente da praticamente tutte le altre (eccettute
  Debian e Slackware).

  Di conseguenza,  una buona idea per il sito del proprio progetto
  fornire tanto pacchetti RPM installabili quanto archivi tar.



