Queste sono alcune linee guida generali da seguire per lo sviluppo:

• Eseguire sempre l'inserimento (check in) dei cambiamenti con repoman; usare repoman commit al posto di cvs commit.
• Se un pacchetto è corrotto anche nella sua versione corrente o se ha un processo di compilazione/installazione veramente orribile, verificare come si comportano altre distribuzioni:
  • Debian
  • Mandriva
  • Fedora
• Il proprio pacchetto, nel momento in cui risulta completato e non mascherato, si suppone funzioni da subito per l'utente finale. La modifica del prodotto installato per farlo funzionare dovrebbe essere opzionale; per questo motivo bisogna installare il pacchetto con delle ragionevoli impostazioni predefinite.
• Non aver timore di consultare la documentazione in linea di Gentoo e di guardare come sono scritti e mantenuti gli ebuild creati da sviluppatori più esperti. Non farsi problemi a contattare direttamente sviluppatori più esperti per porre qualsiasi domanda di natura tecnica o di regolamento.
• Fare attenzione riguardo ai propri commit. Ricordarsi che i propri cambiamenti possono potenzialmente danneggiare migliaia di utenti. Se i propri cambiamenti causano qualsiasi tipo di malfunzionamento nel portage tree, devono essere corretti in modo tempestivo
• Ogni pacchetto deve essere accompagnato da un file metadata.xml il quale elenca, tra le diverse informazioni, quale herd /gruppo) (e/o quali mantenitori) sono incaricati del pacchetto.

Su certe architetture, le librerie condivise devono essere compilate con -fPIC. Nell'architettura x86 ed in altre, le librerie condivise possono compilare senza -fPIC, ma è uno spreco e potenzialmente potrebbe causare una diminuzione di prestazioni. Se viene trovato un pacchetto che non compila le librerie condivise con -fPIC, correggere il Makefile per compilare solo le librerie condivise con -fPIC. Sono disponibili maggiori informazioni su PIC alla pagina http://www.gentoo.org/proj/en/hardened/pic-internals.xml (ndT: in inglese). Se non si è sicuri, chiedere aiuto in un forum pubblico di sviluppatori (come la mailing list gentoo-dev o sul canale irc #gentoo-dev).

I nuovi moduli Perl saranno aggiunti al portage solo quando una delle seguenti condizioni sarà verificata:

• I(l) modulo(i) soddisfa una dipendenza
• I(l) modulo(i) non può essere gestito da g-cpan
• I(l) modulo(i) aggiunge funzionalità agli ebuild esistenti
• I(l) modulo(i) fornisce strumenti, applicazioni o altre funzionalità (per esempio di più di quelle che offre il loro .PM)

Assicurarsi che almeno un membro dell'herd di perl approvi questo tipo di aggiunte.

Il nome del file dell'ebuild consiste in quattro sottosezioni logiche:

pkg-ver{_suf{#}}{-r#}.ebuild

La prima sottosezione, pkg, è il nome del pacchetto, il quale deve contenere soltanto caratteri minuscoli, i numeri 0-9, qualsiasi numero di trattini singoli (-), underscore (_) o caratteri più (+). Esempio: util-linux, sysklogd e gtk+. Ci sono alcuni pacchetti in Portage che non seguono queste regole, ma il proprio pacchetto le dovrà seguire.

La seconda sottosezione, ver, è la versione del pacchetto, che normalmente dovrebbe essere uguale alla versione del file archivio dei sorgenti principale. La versione è normalmente composta da due o tre (o più) numeri separati da punti, come 1.2 o 4.5.2, e potrebbero avere una singola lettera alla fine dell'ultima cifra; per esempio, 1.4b o 2.6h. La versione del pacchetto è unita al nome del pacchetto con un trattino. Esempio: foo-1.0, bar-2.4.6.

La terza sottosezione, {_suf{#}}, è opzionale è può contenere uno di questi suffissi predefiniti, elencati dal meno recente al più recente:

Qualsiasi di questi suffissi può essere immediatamente seguito da un numero positivo diverso da zero, per esempio, linux-2.4.0_pre10. Assumendo la parte della versione identica, il suffisso è ordinato come segue (più basso significa più vecchio): _alpha <_beta < _pre < _rc < (no suffix) < _p.

Quando si confrontano suffissi identici seguiti da un intero, quello con il numero più grande viene considerato il più recente. Esempio: foo-1.0_alpha4 è più recente di foo-1.0_alpha3.

La quarta sottosezione del nome del pacchetto è il numero specifico della revisione Gentoo Linux ({-r#}). Questa sottosezione, come il suffisso, è opzionale. # è un numero positivo diverso da 0 zero; esempio, pacchetto-4.5.3-r3.

Questo numero di revisione è indipendente dalla versione del relativo file archivio dei sorgenti, ed è usata per informare le persone della disponibilità di una nuova e migliorata versione di un particolare pacchetto per Gentoo Linux. Il rilascio iniziale degli ebuild non deve avere il numero della revisione, per esempio package-4.5.3 ed è considerata da Portage come se avesse un numero di revisione pari a zero. Questo significa che il conteggio viene fatto in questo modo: 1.0 (versione iniziale), 1.0-r1, 1.0-r2, ecc.

Il numero della revisione di un pacchetto deve essere incrementata dagli sviluppatori di Gentoo Linux quando l'ebuild ha ricevuto delle modifiche che impongono agli utenti di effettuare un aggiornamento. Generalmente, questo è il caso in cui le correzioni vengono fatte su di un ebuild che influenza i file installati, ma l'ebuild usa lo stesso file archivio del precedente rilascio. Se viene fatto un cambiamento interno all'ebuild di tipo stilistico il quale non modifica nessun file installato, allora non è necessario incrementare il numero della revisione. Allo stesso modo, se nell'ebuild viene corretto un problema di compilazione che affliggeva alcuni utenti non è necessario incrementare il numero della revisione, in quanto per tutti quelli a cui il pacchetto funziona perfettamente non avranno benefici nell'installare una nuova revisione, e quelli che hanno avuto problemi di installazione non avranno il pacchetto installato (perché la compilazione è fallita) per cui non c'è bisogno di fare una nuova revisione per forzare un aggiornamento. La pubblicazione di una revisione non è inoltre necessaria se il problema è stato riscontrato da un numero minimo di utenti ed il pacchetto ha un tempo medio di compilazione non trascurabile; in queste circostanze usare il proprio giudizio nel miglior modo possibile.

Gli ebuild devono essere basati sulla versione precedente dell'ebuild per assicurare che i cambiamenti non vengano accidentalmente cancellati. Le correzioni devono includere dei commenti appropriati nell'ebuild che spiegano cosa fanno ed il perché sono necessarie. Se non si ha dimestichezza con le correzioni, o non si riesce a determinare se sono veramente necessarie, non si dovrebbe aggiornare l'ebuild.

Ogni volta che un ebuild viene derivato, le funzioni e le variabili al suo interno vengono caricate in memoria dall'interprete dello script. Tuttavia, solo le variabili e le istruzioni che non sono parte di una funzione vengono interpretate: funzioni come src_compile() vengono eseguite da Portage solamente quando l'ebuild ha raggiunto la fase di compilazione.

Il codice contenuto in queste funzioni è considerato di "ambito locale" mentre tutto ciò che sta all'esterno delle funzioni è in "ambito globale", che comporta la loro esecuzione ogni volta che l'ebuild viene derivato.

Un'applicazione esterna (come grep, sed o awk) non dovrebbe mai essere chiamata nell'ambito globale per questioni di prestazioni, e invece dovrebbero essere usate delle alternative come l'uso sostitutivo di funzioni native di bash. Si possono trovare delle utili alternative nella Guida avanzata di scripting Bash (ndT: qui l'originale inglese).

In più, non si può garantire l'esistenza nel sistema delle eventuali applicazioni esterne richiamate nell'ambito globale. Se il comando viene messo in un ambito locale (per esempio, nella funzione pkg_setup()), è possibile garantirne la presenza aggiungendolo alla variabile ${DEPEND} dell'ebuild.

Ci sono due modi differenti di compilare un ebuild basato su sorgenti che provengono da un albero di sviluppo CVS. Il primo e tradizionale metodo è di creare un ebuild di tipo "CVS snapshot" (ndT: "fotografia" del CVS) creando un file archivio (tarball) personale dal repository CVS ufficiale, facendo un mirroring dei sorgenti nel repository ufficiale dei distfile di Gentoo, e scrivendo un ebuild per l'uso specifico di questo file archivio. In seguito si farà riferimento a questi tipi di ebuild CVS con il termine "ebuild per snapshot CVS".

L'altro metodo per la creazione di ebuild basati sul CVS è di usare cvs.eclass per creare un ebuild CVS "live". Questi tipi di ebuild recuperano il più recente codice sorgente in fase di sviluppo dal repository CVS durante la fase di scaricamento (fetch) dei sorgenti, assicurando che i sorgenti siano il più possibile aggiornati. In seguito si farà riferimento a questi tipi di ebuild CVS con il termine "ebuild 'live'" (ndT: "in diretta/dal vivo").

I seguenti paragrafi spiegano in dettaglio le regole riguardanti l'uso di ebuild basati su CVS. Tenere presente che esistono delle regole molto rigide riguardo all'aggiunta di questo tipo di ebuild al Portage tree.

Ebuild per snapshot CVS sono maggiormente preferiti rispetto ad ebuild "live" (che utilizzano cvs.eclass).

Gli ebuild per snapshot CVS sono autorizzati se uno snapshot del CVS contiene delle migliorie conosciute necessarie al regolare funzionamento di un pacchetto software, o si sa (o è stato provato) che la versione da CVS di un particolare pacchetto software semplicemente funziona meglio della normale versione rilasciata.

Ebuild "live" (basati su cvs.eclass) generalmente sono designati per la comodità degli sviluppatori e dovrebbero sempre essere mascherati con una keyword ~[arch]. È impossibile garantire la solidità di un ebuild "live" (basato su cvs.eclass) in quanto l'albero dei sorgenti CVS ufficiale può subire continue modifiche, e conseguentemente questo tipo di ebuild dovrebbero essere sempre mascherati.

Sia per gli ebuild CVS "live" sia per ebuild CVS "snapshot", il relativo sviluppatore ha la responsabilità di assicurare il loro corretto funzionamento; per ovvie ragioni questo è difficile da attuare per gli ebuild di tipo "live" CVS.

Se degli ebuild (di ogni tipo) non funzionano correttamente o risultano fallati, devono essere corretti o rimossi dal Portage tree. Se sono ebuild CVS "live", potrebbero essere mascherati tramite la keyword ~[arch] per tutto il loro ciclo di vita (questa speciale eccezione è spiegata in dettaglio qui sotto).

Se un utente o gli utenti chiedono specificatamente un ebuild CVS "live", è possibile aggiungerne uno per loro. Esso dovrà essere marcato come ~[arch] in modo che altri utenti non lo installino inavvertitamente.

In questo modo, gli utenti (tipo gli sviluppatori) che richiedono questo tipo di ebuild li possono installare ma gli altri utenti saranno protetti da una loro eventuale installazione accidentale. Si ricorda nuovamente che ciò è applicabile solamente a situazioni in cui un utente o degli utenti richiedono specificatamente un ebuild CVS "live" (basato su cvs.eclass). Gli ebuild per snapshot CVS dovrebbero essere aggiunti al Portage tree con l'obiettivo di renderli stabili e fornire un miglior funzionamento rispetto alla versione normale di tale software.

Gli ebuild sottoposti dagli utenti non dovrebbero mai essere accettati così come sono e dovrebbero essere sempre ben testati e verificati prima di effettuarne il commit nel CVS. Se un ebuild sottoposto da un utente ha dei problemi, lo sviluppatore che lo ha ricevuto e gestito ne sarà ritenuto responsabile. Inviandolo al CVS, si attesta che l'ebuild soddisfa tutti gli standard di sviluppo per Gentoo Linux.

Assicurarsi che l'ebuild proposto dall'utente non contenga intestazioni personalizzate come la seguente:

# Ebuild updated by: me <me@me.com>

Questa informazione dovrebbe essere aggiunta al ChangeLog utilizzando in modo corretto la sintassi per i commenti del ChangeLog. Assicurarsi sempre che il ChangeLog contenga i crediti corretti per l'utente che ha sottoposto l'ebuild. Questa informazione deve apparire nella prima riga del ChangeLog.

Assicurarsi inoltre che tutti i nuovi ebuild di cui si effettua il commit contengano la riga seguente:

# $Header: $

Alcuni ebuild sottoposti dagli utenti sono basati su file recuperati tramite rsync, i quali possono contenere intestazione incorrette.

Incoraggiare gli utenti a sottoporre le differenze (diff) per gli ebuild esistenti se stanno sottoponendo un aggiornamento. Facendo questo, è più facile evitare la re-introduzione di bug già corretti nei propri ebuild "nuovi". Se non si sta lavorando su di un diff sottoposto da un utente ma su di un ebuild completo, allora usare il comando diff per vedere cosa è stato cambiato, tenendo attentamente d'occhio qualsiasi cosa che dal proprio ebuild corrente dovrebbe apparire nel nuovo ebuild, o qualsiasi cosa che dovrebbe essere corretta o rimossa nel nuovo ebuild.

Generalmente, lasciare che sia l'utente a fare il lavoro richiesto per aggiornare il proprio ebuild, a meno che non si voglia effettuare una pulizia dell'ebuild a suo vantaggio. Nondimeno il più delle volte è meglio lasciar fare il lavoro all'utente in modo da dargli la possibilità di imparare dai propri errori e inviare ebuild più precisi in futuro. Assicurarsi di essere riconoscenti per qualsiasi ebuild o patch sottoposta, anche se il lavoro non è molto buono. Comportarsi in modo educato ma onesto: se un ebuild non è usabile, l'utente può essere avvisato in un modo da non insultare la sue attuali abilità nello scrivere ebuild. Ricordarsi che l'utente che invia degli ebuild corrotti potrebbe essere in futuro un membro responsabile e produttivo del progetto Gentoo, e questo succederà se riceverà la giusta quantità di incoraggiamenti e supporto per continuare a migliorare le proprie abilità.

Solo i membri del team di Portage (che si sa chi sono) hanno l'autorità per rilasciare una nuova versione di Portage, nessun altro è abilitato a farlo.

Solo i membri del team del baselayout (che si sa chi sono) hanno l'autorità di rilasciare una nuova versione di baselayout, nessun altro è abilitato a farlo.

/usr/portage/profiles/package.mask contiene una lista di pacchetti che non dovrebbero essere installati dagli utenti e i commenti che spiegano in modo dettagliato i motivi dello mascheramento. package.mask è usato per prevenire l'installazione di pacchetti malfunzionanti, che guastano qualcosa d'altro o necessitano di test intensivi prima di essere aggiunti nel ~ARCH KEYWORDS del Portage tree. Quando si aggiunge un pacchetto a package.mask, fare sempre prima il commit di questo file prima del commit dell'ebuild mascherato, in modo da prevenire che l'ebuild venga installato erroneamente dagli utenti, prima che il file package.mask aggiornato lo possa fare da sé.

Ogni volta che un pacchetto viene rimosso da package.mask bisogna fare molta attenzione, poiché c'è un motivo se un ebuild è elencato in questo file. Se non si ha effettuato personalmente il mascheramento dell'ebuild, contattare sempre lo sviluppatore elencato nei commenti di package.mask prima di intraprendere qualsiasi azione. Inoltre, se l'ebuild mascherato è un pacchetto di sistema, o una sua dipendenza, o se la rimozione del mascheramento potrebbe avere effetti dannosi, il cambiamento deve essere discusso internamente nella mailing list degli sviluppatori.

Lo scopo di ~arch è di testare nuovi pacchetti aggiunti a Portage.

C'è una differenza tra l'uso di package.mask e ~arch per gli ebuild. L'uso di ~arch denota il fatto che un ebuild ha bisogno di essere testato. L'uso di package.mask denota il fatto che l'applicazione o la libreria stessa è valutata come instabile. Per esempio, se gimp-1.2.0 è la versione stabile per gli sviluppatori di Gimp, ed è disponibile una nuova versione 1.2.1 contenente delle correzioni, uno sviluppatore dovrà marcare l'ebuild come ~arch per poterlo testare in portage perché il rilascio è valutato come stabile. In un altro caso, se Gimp decide di rilasciare una versione della serie instabile o di sviluppo marcata come 1.3.0, allora questi ebuild dovranno essere messi in package.mask perché il software in sé è di una qualità di sviluppo e gli sviluppatori non ne raccomandano la distribuzione.

Tutti i nuovi pacchetti che vengono inseriti in Portage devono essere marcati come ~arch per la(e) architettura(e) sulle quali si sa che quella versione del pacchetto funziona correttamente. Lo sviluppatore che fa il commit dell'ebuild deve verificare che esso funzioni correttamente e che le KEYWORDS siano corrette.

Quando una nuove versione di un pacchetto dimostra di essere stabile per un sufficiente periodo di tempo ed il mantenitore dei pacchetti di Gentoo è fiducioso nel fatto che l'aggiornamento non creerà problemi alla macchina Gentoo degli utenti, allora può essere spostato da ~ARCH a ARCH. Un'indicazione della stabilità del pacchetto può essere se non vengono verificati o non ci sono bug irrisolti per la versione del pacchetto dopo un mese dalla sua introduzione.

È compito del mantenitore del pacchetto reputare quali versioni sono stabili o se la versione di sviluppo dovrebbe essere in package.mask o lasciata come ~arch.

Bisogna inoltre assicurare che tutte le dipendenze di questa versione del pacchetto siano anch'esse in ARCH.

La politica di di Gentoo Linux richiede che tutti gli ebuild contengano le variabili KEYWORDS, LICENSE, e SLOT. Anche HOMEPAGE, SRC_URI e DESCRIPTION dovrebbero essere incluse eccetto per circostanze particolari. DEPEND (e se necessario, RDEPEND) dovrebbero essere incluse se il proprio pacchetto ha rispettivamente delle dipendenze in fase di compilazione o di esecuzione.

Usare DEPEND per definire le dipendenze necessarie per la compilazione di un pacchetto particolare, ed impostare RDEPEND con le dipendenze richieste per eseguire un particolare pacchetto. RDEPEND dovrebbe essere impostato esplicitamente, anche se RDEPEND=${DEPEND}.

RDEPEND="${DEPEND}
         net-ftp/curl"

È anche importante notare che quando un pacchetto binario .tbz2 viene installato soltanto le dipendenze di RDEPEND vengono soddisfatte; usare questa informazione come aiuto nella scelta delle corrette dipendenze per RDEPEND.

Un pacchetto deve dipendere dalle versioni più vecchie che soddisfano le dipendenze. Se esso funziona con libfoo-1.2.x, non farlo dipendere da libfoo-2.x solo perché questa è la versione che si ha installato.

In generale, i pacchetti dovrebbero dipendere da =libfoo-1.2* invece che da >=libfoo-1.2. Altrimenti, le cose potrebbero cominciare a non funzionare più nel momento in cui viene introdotto libfoo-2.0.

La dipendenza da un pacchetto virtuale come virtual/foo funzionerà soltanto se i diversi pacchetti forniti da virtual/foo hanno delle interfacce uguali tra loro. Considerare virtual/jdk-1.3 come esempio: alcuni pacchetti non funzionano con ibm-jdk-1.3 mentre funzionano correttamente con sun-jdk-1.3. Per questa ragione, assicurarsi che il proprio pacchetto sia testato con tutti quelli forniti dal pacchetto virtuale, prima di rimuovere il mascheramento. Si potrebbe fare dipendere il pacchetto soltanto da una parte di quelli contenuti nel pacchetto virtuale piuttosto che dal pacchetto virtuale stesso.