Guida ai Rilasci del Manuale Gentoo

1.  Introduzione

Obiettivo

Questo documento è pensato per aiutare il coordinatore del rilascio del Manuale (e/o altri membri del GDP e collaboratori) ad affrontare l'arduo compito di aggiornare ed allineare tutti i Manuali e la relativa documentazione per il rilascio più recente di Gentoo Linux.

È progettato per ridurre il carico di stress e fatica dovuto ad un processo non pianificato e senza regole prefissate, ed introdurre invece un po' di ordine logico. Troppo spesso il peso di aggiornare tutta la documentazione tende a ricadere su una singola persona (e l'autore può confermarlo in più di un'occasione). Che questo accada o no per un particolare rilascio, questa guida fornisce comunque un piano intelligente e sensato per rendere i documenti pronti per la partenza.

Questo documento fornire delle linee guida su cosa fare e quando farlo, sebbene siano solo delle linee guida; ci sono poche regole rigide, salvo gli aspetti di codifica GuideXML e le regole di commit, come spiegato in documenti tipo la Guida a GuideXML e i Trucchi e consigli per lo sviluppo della documentazione.

2.  Cosa monitorare

Date di rilascio

Per riuscire a pianificare i propri compiti e fare una stima delle date di completamento per l'elenco delle cose da fare (TODO), bisogna avere un'idea di quando avverrà il prossimo rilascio. Gentoo opera con una tabella di marcia solitamente chiamata rilascio cumulativo. I pacchetti vengono costantemente aggiornati; un nuovo rilascio di Gentoo non è nient'altro che un aggiornamento ai supporti d'installazione, stage, snapshot di Portage, e così via. Tuttavia, ciò implica sempre un pesante cambiamento nel Manuale d'Installazione e ad altra documentazione collegata, in quanto devono essere in linea con i nuovi supporti d'installazione.

I nuovi rilasci avvengono ogni 6 mesi circa, sebbene questa non sia una regola fissa, pertanto assicurarsi di controllare costantemente il piano di lavoro (roadmap) per i rilasci. Inoltre assicurarsi di verificare con i membri del team Ingegneria dei Rilasci ("Release Engineering, abbreviato in "releng", ndT) quando i tempi di rilascio si avvicinano, nel caso in cui la "roadmap" non sia stata aggiornata.

Manuali

Sicuramente gli elementi più importanti da aggiornare sono i manuali.

1. Manuale d'Installazione: il manuale più sostanzioso. Questo ha la priorità maggiore, poiché questo è il documento utilizzato dagli utenti quando vogliono installare Gentoo. Il manuale per ciascuna architettura richiede tempo, energia e cure amorevoli. Il manuale viene proposto in due modalità, con collegamento alla rete Internet ("networked", ndT) e senza collegamento alla rete Internet ("networkless", ndT). Entrambi hanno la medesima priorità, sebbene giusto prima del rilascio bisognerebbe focalizzarsi maggiormente sul completamento del manuale "networkless", in quanto releng avrà bisogno degli archivi tarball di tale documento per metterli nei liveCD prima dell'effettiva data di rilascio.
2. Manuale di Portage: Non viene modificato spesso come il Manuale d'Installazione, ma ha bisogno comunque di essere aggiornato a seguito di nuovi file di configurazione e variazioni nei nomi, per esempio i cambiamenti in /etc/make.conf e /etc/conf.d/. L'altro Manuale di Portage è più approfondito. Fare delle verifiche insieme ai mantenitori di baselayout e Portage per assicurare che le informazioni sia aggiornate.
3. Il Manuale per la configurazione di Rete: Verrà aggiornato ogniqualvolta verranno aggiornate le sezioni principali della configurazione di rete nel Manuale d'installazione, in quanto alcune informazioni sono similari. Nuovamente, fare una verifica insieme ai mantenitori di baselayout e Portage per assicurare che le informazioni siano aggiornate.

Variabili ed inclusioni condizionali sono una salvezza, è sempre meglio usarli! Oggetti specifici per le architetture, che cambiano costantemente, come le dimensioni delle immagini ISO, CFLAGS raccomandate, versioni dei kernel, ecc. sono raccolte nei file handbook-$arch, nella parte iniziale. Releng saranno a conoscenza dei parametri di boot dei CD, dimensioni dei supporti e degli scaricamenti ("download", ndT), i requisiti minimi di sistema, nonché dei i supporti disponibili e i relativi nomi dei file. I team delle architetture saranno a conoscenza delle CFLAGS e i nomi dei kernel e relative configurazioni, oltre agli schemi di partizionamento suggeriti e strumenti specifici da installare/usare.

Quando possibile, provare a farsi aiutare dai membri dei team delle architetture a tenere traccia di tutte le informazioni che cambiano da rilascio a rilascio. Vedere se hanno delle persone dedicate per contribuire alla verifica dei cambiamenti della documentazione; è sempre meglio se hanno qualcuno che può proporre patch GuideXML, perciò non esitare a chiedere! Per cui assicurarsi di mettere in CC i team delle architetture nel bug di tracciamento per il rilascio del manuale in modo da tenerli aggiornati.

Talvolta i rilasci introdurranno abbastanza cambiamenti da necessitare la stesura di un nuovo capitolo o perfino di un intero manuale, oppure anche una rimozione completa. Rimanendo funzionali il più possibile, cercare di non duplicare informazioni tra i file del manuale per architetture separate. Invece, vedere se si riesce a combinarle in un singolo file attraverso un uso intelligente delle inclusioni condizionali. Quando avvengono questi tipi di addizioni/sottrazioni, bisogna effettuare le variazioni appropriate ai file handbook-$arch.

Altri documenti

Insieme ai manuali, bisognerà anche aggiornare simultaneamente i seguenti documenti per tenerli allineati con i manuali. I documenti vanno e vengono ma questi sono i file maggiormente critici di cui tener traccia.

• Guide Rapide all'Installazione, che includono quelle per x86, Sparc, FreeBSD e ogni altra architettura per la quale c'è una guida rapida all'installazione in /doc/en. Esse includono qualsiasi tipologia di guide ai Metodi Alternativi per l'Installazione, guide a LVM2, Trucchi e consigli per l'installazione, e così via.
• FAQ, incluse le FAQ generiche e le FAQ specifiche per architettura, come quelle per AMD64, PPC, Sparc, ecc. Si include anche qualsiasi guida di compatibilità o sui requisiti specifici per architettura, come per MIPS. Qualsiasi cosa relativa alle architetture supportate può variare da rilascio a rilascio; bisogna quindi contattare i vari team delle architetture per individuare tali cambiamenti.
• Guida a Gentoo Linux LiveUSB, per le persone che vogliono usare una chiave USB al posto dei dei CD d'installazione. Verificare attentamente che i parametri di boot, nonché il processo di creazione del supporto, siano ancora corretti.
• Guide di aggiornamento, per esempio la Guida all'aggiornamento di Gentoo, in quanto questo documento contiene le informazioni per l'aggiornamento del profilo. Molti rilasci includono nuovi profili e rendono deprecati o rimuovono vecchi profili. Inoltre, qualsiasi cambiamento introdotto da baselayout tra dei rilasci avrà tutte le relative informazioni di aggiornamento spiegate in dettaglio in questo documento.
• Guida alla configurazione del kernel. Mantenere le opzioni raccomandate e disponibili in questo file sincronizzate con quelle del Manuale d'Installazione.
• metadoc.xml, che conterrà i collegamento aggiornati ai file correnti del manuale, sia quello con collegamento ad Internet ("networked", ndT), sia quello senza ("networkless", ndT).

3.  Effettuare il commit

Linee guida generali

Ricordarsi, prima di effettuare il commit di qualunque cambiamento ad un documento, di validare il file con xmllint --valid --noout. Qualità! Aspirare alla perfezione tecnica e procedurale. Eviterà molti dispiaceri al responsabile di questo importante compito, quando verrà l'ora dell'effettivo rilascio.

Evitare di mischiare correzioni ortografiche, grammatiche, o di stile di codifica GuideXML con le correzioni informative/procedurali (cambiamenti di contenuto), altrimenti si rischia di mettere in seria difficoltà i traduttori; meglio evitarlo. Cercare di effettuare prima i commit delle correzioni dei contenuti, poi quelle non per il contenuto.

Non importa effettuare l'incremento delle date quando si sta lavorando sulle proprie bozze fuori linea. Risparmiare l'incremento finale di data per il commit "in linea" definitivo. Tuttavia, si potrebbe voler effettuare l'incremento al numero di versione corretto prima del commit "in linea", tanto per togliersi il pensiero. È anche un indicatore pratico per ricordarsi se si ha aggiornato o no la data del file. Quando si è pronti per il commit finale, assicurarsi di verificare la versione e le date per ciascun file. (È consigliabile prendersi qualche caffè; il processo è noioso ma necessario.)

Per quanto possibile, cercare di mantenere il testo e il layout delle sezioni (incluso l'ordine) identico tra i diversi manuali delle architetture, specialmente per il contenuto condiviso.

Se si includono dei <-- TODO comments --> nei documenti come note per sé stessi, assicurarsi di rimuoverle prima di effettuare il commit del documento definitivo, in modo da non fare confusione.

Quando si è pronti per il commit "in linea", non dimenticarsi di rimuovere qualsiasi disclaimer "draft" dai collegamenti dei file.

4.  Procedure consigliate

Le procedure seguenti non devono essere eseguite in uno specifico ordine, ma sono comunque raccomandate. Aiuteranno a fare un uso efficiente del proprio tempo, limitando il più possibile gli errori. Questo ordine di procedimento (o qualcosa di simile ad esso ;) ) ha funzionato piuttosto bene per gli ultimi rilasci.

Revisione delle bozze

Cominciare con i manuali d'installazione:

1. Creare la directory per il nuovo manuale per l'installazione senza collegamento ad Internet ("networkless", ndT); es. handbook/2007.1/
2. Copiare tutti i file dell'attuale manuale "networkless" nella directory del nuovo manuale. Non ci sono problemi se questa directory è effettivamente "in linea", in quanto non verrà inserito nessun collegamento ad essa dalle pagine degli indici.
3. Copiare i file dell'attuale manuale d'installazione via Internet ("networked", ndT) in handbook/draft/
4. Effettuare il commit di queste aggiunte. Fare una copia diretta senza nessuna modifica! Altrimenti c'è il rischio di complicare il lavoro dei traduttori nel seguire le modifiche
5. Modificare le pagine handbook-$arch.xm del manuale "networkless", assicurandosi che abbiano il disclaimer "draft" nel proprio collegamento interno (attributo "link" del tag <guide> , ndT)
6. Scorrere i vari file e rinumerare i vecchi nomi/numeri di rilascio a quello imminente, es. 2007.0 --> 2007.1. Questo è anche il momento giusto per effettuare l'incremento alla versione superiore ("major version", ndT) per ciascuna pagina. Ciascun rilascio riceve un numero di <version> superiore. Perciò, per esempio, i riferimenti a 2007.0 in hb-install-kernel.xml diventano 2007.1, ed il contenuto di <version> del file viene incrementato da 7.4 a 8.0. Se è 4.3, diventa 5.0, e così via.
7. Iniziare ad introdurre i cambiamenti di contenuto (e non) ai file, prestando attenzione a non mischiare le due cose. Ricordarsi che la maggior parte dei cambiamenti, ma non tutti, si applicheranno sia al manuale "networked" che a quello "networkless" pertanto essere cauti quando si raddoppieranno i propri commit. Inoltre, fare attenzione ai cambiamenti del manuale che hanno bisogno di essere propagati anche ai file non di manuale, per esempio le FAQ.
8. Fare le modifiche necessarie ai file non appartenenti al manuale, ma cercare di mantenerli fuori linea, come spiegato qui sotto.

Preparare i manuali "networkless" da inserire su disco

I manuali "networkless" dovranno essere pronti qualche giorno prima della data reale di rilascio, in quanto i membri di releng dovranno inserirli nelle immagini ISO un po' in anticipo. Ovviamente, bisogna mantenere i manuali "networkless" il più aggiornati e perfetti possibile; idealmente con incrementi di versione, e anche di data, giusto prima di doverli racchiudere nell'archivio tarball.

Sfortunatamente, il team GDP non ha più uno script funzionante per convertire i manuali nella versione HTML che va a finire sul disco. In alternativa, usare il codice sorgente online renderizzato in HTML contenuto in /handbook/$nuovo-rilascio/. Scaricare la versione completa Stampabile del codice sorgente dei manuali per le architetture richieste usando il proprio browser preferito, salvandolo come index.html.

(Creare la directory che verrà compressa con tar)
$ mkdir -p handbook/html/css
$ cd handbook/html/
(Spostare qui il file HTML)
$ mv ../../index.html ./
(Scaricare il CSS di Gentoo)
$ wget http://www.gentoo.org/css/main.css -O css/main.css

Successivamente bisognerà modificare il file HTML con il proprio editor preferito. Cambiare il collegamento CSS nella testata del documento in css/main.css come mostrato:

<link title="new" rel="stylesheet" href="css/main.css" type="text/css">

Salvare i cambiamenti, poi creare un archivio tar della directory principale handbook appena creata. Salvarlo come handbook-arch.tar.gz (dove arch è il nome dell'architettura), infine spedirlo al team releng. Ripetere l'operazione per ciascuna architettura che ha un manuale d'installazione "networkless".

Effettuare il commit, includendo il rilascio finale

1. Appena si pensa di essere pronti per il rilascio, tornare indietro ripassando ciascuno dei file e verificare che il codice XML sia valido e ben formato. Correggere ora qualsiasi errore, non quando si andrà ad effettuare il commit finale.
2. Verificare che le versioni e le date dei file siano state propriamente incrementate
3. Rimuovere i disclaimer "draft" dalle pagine indice handbook-$arch per i manuali "networkless".
4. Rimuovere qualsiasi commento <-- TODO --> o nota inseriti in precedenza.
5. Assicurarsi di aver creato gli archivi tar per i manuali "networkless" ed averli spediti al team releng per i CD d'installazione, come delineato precedentemente.
6. Spostare i file da handbook/draft/ in handbook/, sovrascrivendo i vecchi e rimuovendo i file obsoleti dove necessario.
7. Assicurarsi che metadoc.xml sia corretto.
8. Verificare manualmente che ogni singolo file che si ha modificato sia effettivamente corretto sotto ogni aspetto. (Anche qui torna utile un bel po' di caffè).
9. Assicurarsi di non aver dimenticato nessuna patch o contenuto dal bug di tracciamento per il rilascio del manuale.
10. Nel momento in cui si è convinti che tutto sia pronto, spostarsi con il comando cd nella directory più in alto, solitamente /doc/en/ ed effettuare un commit atomico, in modo da mettere in linea tutto il contenuto nello stesso momento.
11. Comunicare con i propri compagni sviluppatori: inviare annunci/aggiornamenti di stato sul bug di tracciamento e ad ogni mailing list necessaria.
12. Fare un respiro profondo
13. Fare un passo indietro e ri-esaminare ogni singolo file di cui si ha appena effettuato il commit. Magari si può controllare gentoo-doc-cvs, in quanto c'è sempre qualcosa che potrebbe essere sfuggito; ora è il momento per assicurarsi di non aver dimenticato alcun contenuto.

Infine, una volta che il rilascio è pubblico, e tutto fila più o meno bene, proseguire e chiudere il bug di tracciamento. Bella sensazione, vero? Ora bisognerà correggere i bug report degli utenti e dei sviluppatori man mano verrano inseriti!

E poi, prima di accorgersene, sarà ora di iniziare il ciclo di rilascio un'altra volta ancora . . . :)

5.  Breve lista di controllo pre-rilascio

Questa è una versione ridotta di quanto scritto in precedenza, da fare immediatamente prima del commit "in linea" finale:

• File del manuale "networked" in handbook/draft/. Controllare le pagine handbook-$arch pages. Sistemare i collegamenti interni/esterni ai documenti, numeri di versione di rilascio, e incrementi di revisione dei file e date.
• Le pagine index.xml del manuale; verificare le traduzioni elencate e altre informazioni.
• File del manuale "networkless" in handbook/$new-release/. Stessi controlli dei file del manuale "networked". Rimuovere i disclaimer "draft".
• Controlli del manuale di Rete per handbook/draft/: attuale e consistente.
• Controlli del manuale di Portage per handbook/draft/: attuale e consistente.
• Controlli del manuale sulla Sicurezza per /doc/en/security/: ha un basso livello di manutenzione, verificare comunque in ogni caso.
• Controllare /doc/en/ per modifiche in sospeso per questi file contenuti nel livello superiore. Si includono le guide veloci all'installazione, FAQ, guide di aggiornamento, guide per il kernel, ecc.
• Controllo di metadoc.xml: verificare i file che compongono il nuovo rilascio. Sovrascrivere le vecchie voci ed effettuare un incremento di versione di metadoc.
• Validare ogni singolo file contenuto in /doc/en/, handbook/draft/, e handbook/$new-release/ tramite xmllint --valid --noout. Sì, ancora. Correggere gli errori.
• Controllare il bug di tracciamento per il rilascio del manuale per qualunque compito rimanente.
• Spostarsi con il comando cd in /doc/en/ ed effettuare il commit atomico.

I contenuti di questo documento sono rilasciati sotto la licenza Creative Commons - Attribution / Share Alike.