Guida a Gentoo ProjectXML

1.  Introduzione

Cos'è ProjectXML?

ProjectXML è progettato per essere un semplice strumento per creare pagine di progetto che seguano lo stile del sito Gentoo. È usato lo stesso stile XML dei documenti GuideXML.

Conoscenze raccomandate

ProjectXML è progettato per essere di facile utilizzo, pertanto non è necessaria nessuna conoscenza specifica. L'unica lettura raccomandata prima di creare una pagina di progetto è il documento ufficiale Guida a Gentoo XML.

2.  Creare una pagina di progetto

Informazioni generali

Per cominciare a scrivere una pagina di progetto, prima di tutto, bisogna definire le intestazioni appropriate del documento. Basta un copia e incolla delle seguenti righe:

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet href="/xsl/project.xsl" type="text/xsl"?>
<?xml-stylesheet href="/xsl/guide.xsl" type="text/xsl"?>
<!DOCTYPE project SYSTEM "/dtd/project.dtd">

La prima parte del documento è la sezione dei dati generali che si occupa delle informazioni basilari del progetto. Inoltre, in questa sezione si trovano gli unici tag obbligatori, è necessario impostarli per creare una pagina valida: <name>, <longname>, <description> e <longdescription>, anche se è raccomandato l'uso di tutti i tag per dare una visione completa del progetto.

<project>
<name>ProjectXML</name>
<longname>Una pagina di esempio su ProjectXML</longname>
<date>2007-04-15</date>

<description>
Una frase corta per descrivere il progetto.
</description>

<longdescription>
<p>
Una descrizione più elaborata del progetto ( redatta come un blocco GuideXML).
</p>
</longdescription>
</project>

Definire gli obiettivi del progetto

Per mostrare l'obiettivo finale del progetto, ProjectXML usa i tag goals per includere una descrizione circa lo scopo del lavoro. Può essere sufficiente anche una singola frase.

<goals>
<p>
L'intenzione del progetto è di mostrare come creare facilmente una pagina progetto di base usando ProjectXML.
</p>
</goals>

Lista dei collaboratori del progetto

ProjectXML permette di includere una lista di collaboratori Gentoo che sono coinvolti nel progetto. È necessario solamente scrivere il nickname del collaboratore dentro il tag ed automaticamente esso sarà completato con il nome reale quando la pagina viene elaborata e visualizzata.

<dev role="Manager Strategico" description="Politiche e relazioni">Dev1</dev>
<dev role="Manager Operazionale" description="Sicurezza">Dev2</dev>
<dev role="membro">Dev3</dev>

Come è illustrato nell'esempio, il tag dev supporta due attributi opzionali: role è usato per nominare la posizione del collaboratore all'interno del team e description, che permette di inserire alcuni dettagli sul membro.

Herd esistenti

Un altra sezione interessante da includere in una pagina di progetto è la lista dei Gentoo herd che appartengono al progetto. L'unico dato necessario da riempire è l'attributo name.

<herd name="herd1" />
<herd name="herd2" />

ProjectXML analizza il file herds e nella visualizzazione finale saranno visibili tutti i nickname dei collaboratori che appartengono all'herd.

Risorse del progetto

È inoltre possibile inserire link di risorse all'interno della pagina di progetto. Questi link di solito puntano alla documentazione Gentoo, documenti esterni o siti Internet utili.

<resource link="/gentoo/link.xml"> (http://www.gentoo.org omesso)
<resource link="http://www.sito.internet.utile/">

3.  Rifinire la pagina di progetto

Completare le informazioni generali

Anche se la sezione precedente tratta le informazioni di base per creare un progetto, ci sono altri capitoli che possono essere molto utili da usare in alcuni casi.

Il resto della guida, mostra come aggiungere informazioni extra ai capitoli visti nella sezione precedente, come creare sottoprogetti all'interno della pagina di progetto o come mostrare i lavori e i loro stati.

Includere una sezione per il reclutamento

ProjectXML permette l'inclusione di una sezione che mostra i processi aperti per il progetto o le opportunità di collaborazione. Tutto quello che occorre fare è includere il tag <recruitment> appena prima di </goals>. Per ogni posizione bisognerebbe includere un tag <job>. Al suo interno, si trova <summary>, <details>, <requirements> e uno o più tag <contact>. Ecco un esempio di come utilizzare ciò:

<recruitment>
  <job>
    <summary>First Open Position</summary>
    <details>
      Just an <e>example</e>> of how to write details about this
      first open position
    </details>
    <requirements>
      Needed <b>skills</b> to work in the open position
    </requirements>
    <contact>nick1</contact>
    <contact>nick2</contact>
  </job>
</recruitment>

Tutti i processi pubblicati dai progetti elencati nella nostra relativa pagina appariranno nella nostra pagina Gentoo Linux Staffing Needs.

Aggiungere contenuti extra

Se si pensa che le precedenti sezioni di base siano un po' vuote, o si ha intenzione di arricchirle con una frase o un paragrafo, si possono aggiungere capitoli extra che saranno mostrati appena sotto la sezione desiderata.

Alle seguenti sezioni possono essere aggiunti contenuti extra: goals, devs, resources, subprojects, tasks e recruitment. Tutto quello di cui si ha bisogno è di impostare l'attributo position al tag extrachapter. Il prossimo esempio mostra come aggiungere informazioni alla sezione dei collaboratori:

<extrachapter position="devs">
<title>Note sui collaboratori</title>
<section>
<body>

<p>
La lista degli sviluppatori include solo gli sviluppatori ufficiali di Gentoo ma il progetto funziona grazie a molti altri collaboratori che non sono sviluppatori Gentoo.
</p>

</body>
</section>
</extrachapter>

Inoltre, si possono aggiungere uno o più capitoli extra in cima o in fondo nella stessa pagina. Il capitolo extra in posizione top sarà visualizzato appena sotto la descrizione del progetto e quello in bottom alla fine della pagina.

<extrachapter position="bottom">
<title>Come trovarci</title>
<section>
<title>Via mail</title>
<body>

<p>
Per comunicare con il team della documentazione Gentoo hai bisogno solamente di iscriverti alla nostra mailing list: gentoo-doc@gentoo.org
</p>

</body>
</section>
</extrachapter>

Definire i sottoprogetti

Se il progetto è composto da uno o più sottoprogetti, ProjectXML permette di specificarli in modo da essere visualizzati o linkati dalla pagina principale del progetto.

Per determinare di che tipo di tag di sottoprogetto si necessita, seguire le seguenti istruzioni:

1. Se il sottoprogetto ha la propria pagina ProjectXML, le informazioni di base possono essere estratte da lì e può essere aggiunto alla pagina un link al sottoprogetto. Usare il tag xml subproject.
2. Se il sottoprogetto non ha una sua pagina e si vogliono mostrare le informazioni nella pagina principale, usare il tag xml extraproject.
3. Se il sottoprogetto è stato pianificato, ma ancora non è iniziato, usare il tag xml plannedproject.

Sottoprogetti: È abbastanza semplice aggiungere un sottoprogetto, è necessario solamente inserire il percorso dove è collocata la pagina del sottoprogetto. Sono ammessi inoltre un paio di possibili attributi: inheritmembers che aggiunge i collaboratori del sottoprogetto alla sezione collaboratori della pagina principale. Il secondo è inheritresources che fa lo stesso con la sezione risorse.

<subproject ref="/path/to/subproject.xml" inheritresources="yes" inheritmembers="yes"/>

Progetti Extra: I progetti extra necessitano obbligatoriamente del name del progetto ed hanno la possibilità di definire il lead e un possibile link al progetto. È importante ricordare di includere una descrizione del progetto.

<extraproject name="Primo progetto extra" lead="myself">
  Qui va la descrizione del progetto extra.I tag GuideXML sono supportati se hai bisogno di usarli.
</extraproject>

Progetti Pianificati: per i progetti futuri l'unica cosa necessaria è il name e un testo di descrizione.

<plannedproject name="ProjectXML futuro">
  La descrizione di un progetto futuro va qui.
</plannedproject>

Gestire compiti

Se nel progetto sono stati pianificati alcuni compiti (task) per completare il lavoro, questi possono essere visualizzati nella pagina. I compiti possono essere abbastanza semplici o possono fornire dettagli delle persone che lavorano e dare informazioni circa il loro stato e la descrizione.

Le informazioni necessarie di base da riempire per un compito sono: gli attributi id,lead e finished. Dentro all'elemento task devono essere specificate più informazioni: il <name> del compito, la <description> e lo <startdate>.

<task id="basictask" lead="devnick" finished="no">
<name>Definire un compito di base</name>
<description>Come creare un compito di base</description>
<startdate>01/01/2007</startdate>
</task>

Ci sono altri elementi che possono essere usati per arricchire le informazioni sui compiti:

• Il tag longdescription, che da una panoramica completa dell'attività del progetto.
• Il tag enddate, se il compito è finito mostra il lasso di tempo impiegato.
• Uno o più tag dev, mostra le persone coinvolte nei vari compiti. Il tag accetto gli attributi role e description.
• Uno o più tag reference, include link a informazioni rilevanti. Si può usare il classico <uri>; elemento GuideXML o uno o più tag bug che puntano a Gentoo Bugzilla.
• Uno o più tag milestone, mostrano importanti punti di sviluppo all'interno del compito. I tag milestone usano l'attributo finished e necessitano dei tag enddate e description.
• Uno o più tag depends, mostrano le dipendenze tra i compiti. È necessario riempire l'attributo ref che si riferisce all'id di un altro compito.

<task id="basictask" lead="devnick" finished="no">
<name>Definire un compito completo</name>
<description>Come creare un compito completo</description>
<longdescription>
Una più lunga descrizione su come creare un compito completo.
</longdescription>
<startdate>01/01/2007</startdate>
<enddate>06/04/2007</enddate>
<dev role="designer" description="L'unico designer">dev1</dev>
<reference><uri link="/path/to/doc.xml">Guida principale</uri></reference>
<reference><bug no="145234"/></reference>
<milestone finished="yes">
  <enddate>04/03/2007</enddate>
  <description>Pensando alla scrittura della guida</description>
</milestone>
<depends ref="task1"/>
</task>

4.  Aggiungere un progetto alla lista completa dei progetti Gentoo

Gentoo fornisce una pagina con la lista completa dei progetti appartenenti alla distribuzione. Questa mostra tutti i progetti di livello più alto e i loro sottoprogetti. Tutti i progetti correnti dovrebbero essere elencati qui, questo è quello che si deve fare per aggiungere un progetto alla lista:

Se viene scritta una pagina per un sottoprogetto, basterà che sia elencata nella pagina principale del progetto. (come descritto nella sezione sottoprogetti).

Se è un progetto di alto livello, bisogna aggiungere il progetto a: /gentoo/xml/htdocs/proj/en/metastructure/gentoo.xml:

<subproject ref="/proj/en/myproject/index.xml" inheritmembers="no"/>

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