Overlay Gentoo: Guida per gli Sviluppatori

1.  Introduzione

I destinatari

Questo documento è stato scritto per gli sviluppatori e utenti di Gentoo che vogliono dare il proprio contributo. Se si vuole semplicemente iniziare a scaricare ed usare gli overlay, è meglio consultare la Guida utente agli Overlay di Gentoo.

Chi può usare overlays.gentoo.org?

Ogni progetto Gentoo, o ogni sviluppatore Gentoo, può avere un proprio overlay ospitato su (git.)overlays.gentoo.org, con un RSS alimentato dal changelog incluso sul planet di overlays.gentoo.org.

Qualsiasi utente può scaricare e usare i contenuti di qualunque overlay ospitato. Se uno sviluppatore lo desidera, può concedere il diritto di scrittura sul proprio overlay agli utenti.

Cosa può offrire overlays.gentoo.org?

Il servizio (*.)overlays.gentoo.org attualmente offre:

• Trac (un ambiente wiki con navigatore di versioni incorporato), per creare e mantenere rapidamente documentazione per il proprio overlay basato su Subversion
• La pubblicazione del changelog per il proprio overlay sulla homepage di o.g.o, in modo che chiunque sia interessato può vedere come si sviluppa il progetto
• gitweb - fornisce un'interfaccia web completamente matura per visualizzare i repository Git.

... tutto ospitato sulla sicura, protetta da backup, infrastruttura Gentoo, amministrata dal team Infrastruttura Gentoo (hardware / base OS) e dal team Gentoo Overlays (wiki / VCS / ACL).

Ciascun overlay ha liste di autenticazione separate per Trac, Subversion e Git. Non è assolutamente un problema dare a qualcuno l'accesso in scrittura solo per Trac (ad esempio per scrivere documentazione) senza dare l'accesso in scrittura a Subversion.

Perché si dovrebbe usare overlays.gentoo.org?

Non è necessario. Non è assolutamente necessario avere un overlay, e, nel caso lo sviluppatore ne avesse già uno, è assolutamente libero di ospitarlo altrove. Non è necessario ospitare un overlay su o.g.o affinché questo sia considerato "ufficiale".

Il vantaggio di usare overlays.gentoo.org è che tutti gli strumenti sono già pronti all'uso. Non è necessario amministrare un proprio server o preoccuparsi degli aggiornamenti software, in quanto ci pensano i responsabili degli Overlay.

Quando overlays.gentoo.org non si dovrebbe usare?

Lo scopo di o.g.o è aiutare a colmare il divario tra sviluppatori e utilizzatori. Gentoo è una distribuzione basata sulla comunità, ed come tale crede che i propri utenti siano una parte fondamentale della comunità così come lo sono gli sviluppatori.

Tutti gli overlay ospitati su o.g.o sono disponibili per il download e l'uso da parte di tutti gli utenti. Sta agli utenti scegliere quale software installare sui propri computer, e la scelta include la possibilità di scegliere l'overlay di uno dei sviluppatori. Qualche utente prenderà decisioni sbagliate, che porteranno al crash del suo computer. Potranno persino finire con l'incolpare Gentoo come risultato. Ciò è normale; questa gente probabilmente va comunque in giro a incolpare tutti tranne loro stessi per i loro errori, e probabilmente non c'è nulla da fare per cambiare questa situazione. Ma questo non dà comunque a nessuno degli sviluppatori il diritto di scegliere per loro.

Gli utenti sono liberi (di fatto sono incoraggiati) a fornire riscontri costruttivi su qualsiasi cosa che abbia a che fare con Gentoo, inclusi tutti gli overlay ospitati su o.g.o.. I feedback possono arrivare tramite bugs.g.o, via email al team del proprio progetto o direttamente allo sviluppatore, tramite i forum, o tramite IRC. Non si sta parlando di utenti "fraudolenti"; non c'è tempo per loro, e nessuno si aspetta che ne abbiano gli sviluppatori.

o.g.o. aveva delle restrizioni per quanto riguardo all'impossibilità di essere $UPSTREAM per i pacchetti. Questa restrizione è stata corretta. Ora viene offerto l'hosting come $UPSTREAM, ma solo per pacchetti che sono specifici per Gentoo o importanti per il suo funzionamento. Altri servizi di hosting risultano essere più adatti, per esempio SourceForge.net, Berlios, GentooExperimental.org di Patrick, GitHub o Gitorious.

2.  Richiedere un Overlay

Introduzione

Ci sono tre tipi di overlay - overlay per "progetti", overlay per "sviluppatori" e overlay per utenti. La sola differenza tra di loro è la responsabilità e il tipo di account.

Overlay per i Progetti

Gli overlays per "progetti" sono overlay per i progetti ufficiali Gentoo. Un esempio è l'Overlay PHP.

Un progetto ufficiale Gentoo è un progetto che ha una pagina su www.gentoo.org, e ha un capo eletto. (Questa definizione viene dal documento di metastruttura). I(l) capo(i) progetto sono responsabili per l'overlay del progetto stesso, inclusi i suoi contenuti, e per ogni altro problema che esso causi ad altri progetti e sviluppatori Gentoo.

Per richiedere un overlay SVN di progetto il capo progetto deve solo entrare dentro #gentoo-overlays su IRC e chiedere la creazione di un overlay. Oppure, se lo preferiscono, devono inviare una email a overlays@gentoo.org. Il team Overlays curerà tutto il resto, incluso il garantire l'accesso in scrittura a tutti i membri del proprio progetto (così come elencati nella propria pagina di progetto).

Per richiedere un overlay Git di progetto, basta visitare il sito git.overlays, e seguire le istruzioni di configurazione, inviando via e-mail il template completato a chi di dovere.

Per un overlay SVN Il team Overlays:

• creerà l'overlay per il progetto (sito trac + svn)
• aggiungerà il feed RSS dell'overlay del progetto all'homepage o.g.o.
• creerà un account o.g.o per lo sviluppatore che ha fatto la richiesta, se non ne ha già uno
• gli darà accesso in scrittura al Trac wiki e al repository Subversion, se necessario
• darà accesso in scrittura a tutti i membri del progetto che già hanno un acconto o.g.o.

Per un overlay Git Il team Overlays:

• creerà l'overlay per il progetto (git, gitweb, no trac)
• aggiungerà il feed RSS dell'overlay del progetto all'homepage o.g.o.
• creerà un account git o.g.o per lo sviluppatore che ha fatto la richiesta, se non ne ha già uno
• gli darà accesso in scrittura al repository degli overlay Git
• darà accesso in scrittura a tutti i membri del progetto che già hanno un acconto o.g.o.

Overlay per lo Sviluppatore

Gli overlay per "sviluppatori" sono proprietà degli sviluppatori Gentoo individuali. Un esempio è l'overlay di beandog.

Se si possiede un indirizzo email @gentoo.org, e se si ha superato il quiz sull'ebuild, allora è possibile avere il proprio overlay personale per sviluppatori su o.g.o.

Per richiedere un overlay SVN come sviluppatore, basta entrare in #gentoo-overlays su IRC e chiedere che venga creato un overlay per sé. Oppure, se lo si preferisce, inviare un email a overlays@gentoo.org.

Per una richiesta SVN il team Overlays:

• creerà l'overlay dello sviluppatore (sito trac + svn)
• aggiungerà il feed RSS del suo overlay all'homepage o.g.o.
• creerà un account o.g.o per lo sviluppatore, se non ne possiede già uno
• gli darà accesso in scrittura al Trac wiki e al repository Subversion

Per una richiesta Git il team Overlays:

• creerà l'overlay dello sviluppatore (git, gitweb, no trac)
• aggiungerà il feed RSS del suo overlay all'homepage o.g.o.
• creerà un account o.g.o per lo sviluppatore, se non ne possiede già uno
• gli darà accesso in scrittura al repository degli overlay Git

Una parola sugli account

Siccome o.g.o è strutturato per supportare una miscela di sviluppatori e semplici utenti Gentoo, non vengono creati account 'reali' a livello di sistema sull'host o.g.o.

3.  Lavorando con il proprio overlay

Introduzione

È possibile accedere al proprio overlay subito dopo la sua creazione. Gli overlay di progetto e di sviluppatore hanno diversi URL, così ognuno può distinguere l'uno dall'altro, ma sono identici per qualsiasi altro aspetto.

*Non* ci sono restrizioni in lettura per overlay o wiki. Ognuno ha pieni diritti di accesso in lettura su tutti gli overlay e i wiki. Se si necessita di un overlay 'segreto' di qualche tipo, allora o.g.o non fa per voi.

Accedere agli Overlay dei Progetti

Se il proprio progetto è chiamato 'foo', il proprio sito Trac wiki avrà il seguente indirizzo: http://overlays.gentoo.org/proj/foo/

Per effettuare il checkout del proprio repository di Subversion, usare:

svn co https://overlays.gentoo.org/svn/proj/foo/

Nonstante sia possibile effettuare azioni in sola lettura tramite l'insicuro protocollo HTTP, bisogna effettuare tutti i commit tramite HTTPS. Se si necessita di passare da una modalità all'altra, usare:

svn sw --relocate http://overlays.gentoo.org/svn/proj/foo/ https://overlays.gentoo.org/svn/proj/foo/

Il team Overlays mantiene , una lista completa di overlay per progetti ospitati su overlays.gentoo.org.

Accedere agli Overlay per Sviluppatori

Se la propria email Gentoo è 'foo@gentoo.org', il proprio sito Trac wiki è disponibile al seguente indirizzo: http://overlays.gentoo.org/dev/foo/

Per effettuare il checkout del proprio repository Subversion, usare:

svn co https://overlays.gentoo.org/svn/dev/foo/

Nonstante sia possibile effettuare azioni in sola lettura tramite l'insicuro protocollo HTTP, bisogna effettuare tutti i commit tramite HTTPS. Se si necessita di passare da una modalità all'altra, usare:

svn sw --relocate http://overlays.gentoo.org/svn/dev/foo/ https://overlays.gentoo.org/svn/dev/foo/

Il team Overlays mantiene , una lista completa di overlay per sviluppatori ospitati su overlays.gentoo.org.

Come iniziare con Trac

Nel proprio overlay viene messo a disposizione Trac. Trac è un wiki, un browser di repository subversion, e un sistema per il tracking dei bug molto popolare tra gli sviluppatori open source.

È stato disabilitato il sistema di bug tracking in Trac. Usare il bugzilla di Gentoo per il bug tracking del proprio overlay.

Il feed RSS del proprio overlay - quello mostrato sull'homepage di o.g.o - deriva dalla pagina Timeline di Trac o dal sommario di GitWeb.

Come iniziare con Subversion

Il vantaggio di Subversion su CVS include il versioning reale delle directory, completo supporto al changeset, ed è molto più semplice eseguire branching all'occorrenza. Lo svantaggio principale è che è più lento di CVS, e che un controllo locale di Subversion richiede più spazio su disco.

Se non si ha mai usato Subversion precedenza, il manuale in linea è un buon metodo per imparare ad usarlo. È possibile anche comprarlo in formato cartaceo, se lo si preferisce.

Qui di seguito ci sono alcuni comandi di base per iniziare.

svn co https://overlays.gentoo.org/proj/php

svn status

svn add my.ebuild

svn commit -m 'La mia voce di Changelog'

Layman

Si raccomanda ad ogni utente di usare layman per scaricare e gestire il proprio overlay. Layman è una utilità scritta da Gunnar Wrobel che rende molto semplice lavorare sugli overlay.

Per iniziare ad usare layman, vedere la documentazione nell'homepage, la Newsletter Settimanale Gentoo del 22 Maggio, o consultare man layman.

Auto-Sync da Portage

I propri pacchetti nell'albero del Portage sono sempre a rischio di essere cambiati senza preavviso. I team Arch devono poter associare keyword ai pacchetti (e correggere incongruenze specifiche per alcune architetture), il team QA deve correggere le violazioni degli standard rilevate, e occasionalmente gli sviluppatori modificano pacchetti che non dovrebbero.

Bisogna essere sicuri che i cambiamenti fatti in Portage non vadano perduti la prossima volta che verranno copiati i pacchetti dall'overlay al Portage.

Il PHP team ha risolto questo problema copiando automaticamente i loro pacchetto dal Portage a un branch del loro overlay chiamato 'portage' ogni notte. Ciò permette loro di usare Subversion (o la timeline di Trac) per vedere le modifiche giornaliere.

4.  Usare git sugli overlay

Inizializzare il proprio overlay

Prima di fare uploading bisogna creare un repository git locale e copiare in esso tutti gli oggetti:

cd ~/my-overlay

git init
git add .
git commit -m "popolare l'overlay"

Notare che questa operazione è solo locale, e con essa il server inizia ad operare.

git-config remote add origin git+ssh://git@git.overlays.gentoo.org/(proj o dev)/(nome)/

git push origin master

Sorgente: http://www.kernel.org/pub/software/scm/git/docs/tutorial.html

Effettuare il checkout dell'overlay con git

git clone git://git@git.overlays.gentoo.org/(proj o dev)/(name)/

5.  Dare ad altri l'accesso al proprio Overlay

Introduzione

Una delle caratteristiche chiave di o.g.o è che chi non ha accesso in scrittura all'albero dei pacchetti del Portage Gentoo può avere accesso in scrittura a uno o più overlay. Diversi progetti Gentoo hanno dimostrato che questo è un ottimo metodo per valutare potenziali sviluppatori Gentoo in un ambiente sicuro.

Overlay dei progetti: come dare accesso in scrittura ai membri del team

Ogni sviluppatore elencato sulla pagina di progetto di un dato team su www.g.o può avere accesso in scrittura all'overlay del team. Il capo progetto può richiederlo in loro vece, o può farlo ogni sviluppatore per conto proprio.

Se lo sviluppatore Gentoo non ha ancora un account su o.g.o, lo dovrà richiedere scrivendo su #gentoo-overlays in modo che i responsabili possano creare il relativo account.

Overlay dei progetti: come dare accesso ad altri sviluppatori Gentoo

Ogni sviluppatore Gentoo *non* elencato sulla pagina www.g.o di un dato progetto può avere accesso in scrittura all'overlay del team. La richiesta per l'accesso in scrittura deve venire da uno dei membri del team. Non è necessario che a richiederla sia il capo progetto.

Se lo sviluppatore non ha ancora un account o.g.o, lo dovrà richiede scrivendo su #gentoo-overlays in modo che i responsabili possano creare il relativo account.

Overlay dei progetti: come dare accesso in scrittura ai semplici utenti Gentoo

Ogni utente Gentoo può avere accesso in scrittura all'overlay di ogni team. La richiesta per accesso in scrittura deve arrivare da uno dei capi progetto. È possibile richiedere che all'utente venga dato accesso in scrittura a Trac, a Subversion, o a entrambi. (Verrà dato per scontato che il diritto di scrittura richiesto sia per entrambi, a meno che non venga esplicitamente detto altro).

Non è possibile accettare richieste di questo tipo da parte di chiunque non sia un capo progetto. Se nel proprio progetto ne esiste uno solo, si raccomanda di eleggerne un secondo. Se il proprio unico e solo capo è AWOL, considerare la possibilità di eleggere un sostituto :)

Se l'utente non ha ancora un account o.g.o,lo dovrà richiedere scrivendo su #gentoo-overlays in modo che i responsabili possano creare il relativo account.

Overlay degli sviluppatori: come dare accesso in scrittura ad altri sviluppatori Gentoo

Ogni sviluppatore Gentoo può avere accesso in scrittura al proprio overlay di sviluppatore. La richiesta può arrivare direttamente dallo sviluppatore; comunque il diritto non sarà concesso fintanto che verrà discussa la cosa con lo sviluppatore di riferimento dell'overlay. Anche quest'ultimo può chiedere che l'accesso in scrittura sia concesso a ogni sviluppatore noto.

Se lo sviluppatore non ha ancora un account o.g.o, lo dovrà richiede scrivendo su #gentoo-overlays in modo che i responsabili possano creare il relativo account.

Overlay degli sviluppatori: dare accesso in scrittura a semplici utenti Gentoo

Ogni sviluppatore Gentoo può avere accesso in scrittura al proprio overlay di sviluppatore. La richiesta del diritto di accesso in scrittura deve venire da parte dello sviluppatore stesso. Si potrà richiedere che all'utente sia dato accesso in scrittura solo a Trac, solo a Subversion, o a entrambi. (Verrà dato per scontato che il diritto di scrittura richiesto sia per entrambi, a meno che non venga esplicitamente detto altro).

Non è possibile accettare richieste di questo tipo da nessun altro tranne lo sviluppatore di riferimento dell'overlay. Se si vede chiaramente che si stanno concedendo accessi a molte altre persone, può essere che sia il caso di considerare il lancio di un nuovo progetto e trasferire il proprio lavoro lì.

Se l'utente non ha ancora un account o.g.o, lo dovrà richiedere scrivendo su #gentoo-overlays in modo che i responsabili possano creare il relativo account.

6.  Come accedere all'Overlay di qualcun'altro

Usare un'Overlay

Chiunque ha accesso in lettura a qualsiasi overlay. Si raccomanda di usare

emerge layman
echo 'source /var/lib/layman/layman.conf' >> /etc/make.conf

Dopo, per vedere la lista di tutti gli overlay, digitare

layman -L

Per installare un overlay, digitare

layman -a <overlay-name>

Dopodiché sarà possibile installare pacchetti provenienti dall'overlay scelto.

Come richiedere l'accesso in scrittura

Se si desidera l'accesso in scrittura ad un overlay di progetto, contattare un membro del team di progetto, e chiedergli il permesso. Se la propria richiesta sarà approvata, provvederanno loro a dare l'accesso in scrittura, contattando il team Overlays.

Se si desidera accedere all'overlay di uno sviluppatore, contattarlo direttamente. Se la propria richiesta sarà approvata, provvederà lui a fornire l'accesso in scrittura, contattando il team Overlays.

7.  Domande frequenti (FAQ)

Amministrazione o.g.o

D: Come posso contattare lo staff admin di o.g.o?

• R: Puoi entrare in #gentoo-overlays su IRC, e parlare con loro lì. Lo staff attuale proviene per la maggior parte da zone con fusi orari europei..
• R: Puoi mandare una email a overlays@gentoo.org. Qualcuno ti risponderà il prima possibile.

D: Perché non posso modificare la lista di controllo degli accessi direttamente?

• R: (SVN) La lista di controllo degli accessi risiede attualmente in formato htpasswd. Solo lo staff admin di o.g.o ha accesso tramite ssh alla box o.g.o.
• R: (Git) La lista di controllo degli accessi risiede attualmente nel repository gitosis-admin, scrivibile solamente dallo staff di o.g.o.

Sicurezza

D: Si puo accedere al mio overlay via https?

• R: Si, si può.

Overlay multipli

D: Posso avere più di un overlay?

• R: Si, in una certa maniera. All'interno del proprio overlay, è possibile creare sub-directory, e mettere alberi di pacchetti all'interno di esse. Si consiglia osservate l'overlay del progetto PHP per avere un esempio.

Importare Overlay preesistenti

D: Io ho già un overlay, e vorrei spostarlo sotto o.g.o. Come devo procedere?

• R: Creare un tarball del proprio repository subversion, e renderlo disponibile allo scaricamento tramite http da qualche parte. Verrà scaricato ed installato dal team Overlays su o.g.o .

D: Io ho un overlay, ma non uso Subversion. Cosa devo fare per spostarlo sotto o.g.o?

• R: Chiede al team Overlays di creare un nuovo overlay vuoto. A questo punto si può usare 'svn import' per importare i propri file nel nuovo overlay. Si perderà la propria storia, ma non è possibile fare altrimenti.
• R: Cercare su internet, e vedere se esiste uno strumento per convertire il proprio software di controllo versioni a Subversion. Se esiste usarlo, e successivamente il team Overlays potrò dare una mano a spostare tutto su o.g.o.
• R: Se il proprio software di controllo versioni è usato da Trac, e può essere usata su HTTP, aiutare il team Overlays a creare un supporto per esso su o.g.o.

Overlay "ufficiali"

D: Quando un overlay è considerato "ufficiale"?

• R: Un overlay "ufficiale" è un overlay gestito da un progetto Gentoo (per overlay dei progetti) o da uno sviluppatore Gentoo (per overlay degli sviluppatori).

D: Un overlay deve essere su o.g.o per essere "ufficiale"?

• R: No.

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