Gentoo Overlays: Guía del Desarrollador

1.  Introducción

Audiencia

Este documento ha sido escrito para desarrolladores de Gentoo y miembros del equipo de Gentoo. Si es usuario de Gentoo, o simplemente desea empezar a usar y descargar los overlays, por favor mire Gentoo Overlays: Guía del Usuario.

¿Quién puede usar overlays.gentoo.org?

Cualquier proyecto de Gentoo, o desarrollador de Gentoo puede tener su propio overlay alojado en *.overlays.gentoo.org, incluyendo el feed RSS de su changelog en el planeta overlays.gentoo.org.

Cualquier usuario puede descargar y usar los contenidos de cualquier overlay alojado. Si lo decide, también puede dar acceso de escritura a su overlay.

¿Qué me da overlays.gentoo.org?

Actualmente el servicio *.overlays.gentoo.org ofrece:

• Trac (un wiki más un navegador de Subversion integrado), para crear y mantener la documentación de su overlay basado en Subversion de manera rápida.
• Publicación del changelog de su overlay en la página principal de o.g.o, de forma que todo el mundo que esté interesado pueda ver lo que está ocurriendo.
• gitweb - ofrece una interfaz web perfectamente preparada para ver los repositorios Git.

... todo alojado en la segura y respaldada infraestructura de Gentoo, administrada por el equipo de infraestructura de Gentoo (hardware / OS base) y el equipo de Overlays de Gentoo (wiki / VCS / ACLs).

Cada overlay tiene listas de autenticación distintas para Trac, Subversion y Git. No hay problema alguno en dar acceso de escritura a alguien solo a Trac (p. e., para escribir documentación) sin darle acceso de escritura en Subversion.

¿Por qué debería usar overlays.gentoo.org?

No tiene que hacerlo. No es necesario que tenga un overlay, y si tiene alguno, es absolutamente libre de alojar su overlay donde desee. No es necesario alojar un overlay en o.g.o para que sea considerado "oficial".

La ventaja de usar overlays.gentoo.org es la de tener todo ya configurado. No necesita administrar su propio servidor, o preocuparse de las actualizaciones de software. Nosotros nos ocupamos de todo eso.

¿Cuándo no debería usar overlays.gentoo.org?

El propósito de o.g.o es el de ayudar a salvar las distancias entre desarrolladores y usuarios. Gentoo es una distribución basada en la comunidad, y creemos que nuestros usuarios son tan importantes en la comunidad como los desarrolladores.

Todos los overlays alojados en o.g.o están ahí para que los usuarios los usen y descarguen desde ellos. Es decisión de los usuarios el software que instalarán en sus computadoras - y eso incluye elegir usar su overlay. Algunos usuarios tomarán malas decisiones, y terminarán malogrando su computadora. Incluso podrían llegar a culpar a Gentoo por ello. Eso está bien; esas personas probablemente vayan culpando a todos excepto a ellos por sus propios errores, y es probable que no pueda hacer nada al respecto. Pero aún así ninguno de nosotros tiene el derecho de elegir por ellos.

Los usuarios son libres (de hecho, los animamos) de brindar opiniones constructivas acerca de cualquier tema relacionado con Gentoo - incluyendo todos los overlays alojados en o.g.o. Esa retroalimentación puede venir vía bugs.g.o., vía correo al equipo del proyecto o al propietario del overlay; vía foros, o por el IRC. No hablamos de los usuarios verdaderamente abusivos; no tenemos tiempo para ellos, y nadie espera que el propietario del overlay lo tenga.

o.g.o tenía restricciones de no ser el $UPSTREAM de los paquetes. Esta restricción ha sido ajustada. Ahora ofrecemos alojamiento como el $UPSTREAM, pero solo para paquetes que son específicos de Gentoo o importantes para que corra el sistema Gentoo. Otros alojamientos pueden ser más adecuados, algunos servicios en esta línea son: SourceForge.net, Berlios, o GentooExperimental.org de Patrick, GitHub o Gitorious.

2.  Solicitando un Overlay

Introducción

Existen dos tipos de overlay - overlays de "proyecto", y overlays de "desarrollador". La única diferencia entre ellos es la responsabilidad.

Overlays de Proyecto

Los Overlays de "Proyecto" son overlays para proyectos oficiales de Gentoo. Un buen ejemplo es el Overlay de PHP.

Un proyecto oficial de Gentoo es aquel que tiene una página de proyecto en www.gentoo.org, y un líder electo. (Esta definición viene del documento de metaestructura). El(los) líder(es) de proyecto son responsables del overlay del proyecto, incluyendo sus contenidos, y cualquier problema que éstos causen a otros proyectos y desarrolladores de Gentoo.

Para solicitar un overlay de proyecto SVN, el líder de éste solo necesita pasar por #gentoo-overlays en el IRC y solicitar que el overlay le sea creado. O, si él/ella lo prefiere, puede enviar un correo a overlays@gentoo.org. Nosotros nos encargaremos del resto, incluyendo otorgar accesos de escritura a todos los miembros del proyecto (listados en la página de su proyecto).

Para solicitar un overlay de proyecto Git, visite el sitio git.overlays, y siga las instrucciones, enviando por correo electrónico la plantilla rellena como está indicado.

Para una solicitud SVN, nosotros:

• crearemos su overlay (sitio trac + svn).
• añadiremos el feed RSS de su overlay a la página de inicio de o.g.o.
• le crearemos una cuenta en o.g.o si no tiene ya una.
• le daremos acceso de escritura al Trac, wiki y repositorio Subversion de su overlay.
• le daremos acceso de escritura a todos los miembros de su proyecto que ya tienen una cuenta en o.g.o.

Para una solicitud Git, nosotros:

• crearemos su overlay (git, gitweb, sin trac).
• añadiremos el feed RSS de su overlay a la página de inicio de o.g.o.
• le crearemos una cuenta en o.g.o si no tiene ya una.
• le daremos acceso de escritura al repositorio Git de su overlay.
• le daremos acceso de escritura a todos los miembros de su proyecto que ya tienen una cuenta en o.g.o.

Overlays de Desarrollador

Los Overlays de "Desarrollador" son overlays manejados individualmente por desarrolladores de Gentoo. Un ejemplo de ello es Overlay de beandog.

Si tiene una dirección de correo electrónico @gentoo.org y ha pasado la prueba de ebuilds entonces puede tener su propio overlay de desarrollador en o.g.o.

Para solicitar un overlay de desarrollador SVN, simplemente ingrese a #gentoo-overlays en el IRC y solicite que el overlay le sea creado. O, si prefiere, envíe un correo a overlays@gentoo.org

Para solicitar un overlay de desarrollador Git, simplemente visite el sitio git.overlays y siga las instrucciones, enviando por correo electrónico la plantilla rellena como está indicado.

Para una solicitud SVN, nosotros:

• crearemos su overlay (sitio trac + svn).
• añadiremos el feed RSS de su overlay a la página de inicio de o.g.o.
• le crearemos una cuenta en o.g.o si no tiene ya una.
• le daremos acceso de escritura al Trac, wiki y repositorio Subversion de su overlay.

Para una solicitud Git, nosotros:

• crearemos su overlay (git, gitweb, sin trac).
• añadiremos el feed RSS de su overlay a la página de inicio de o.g.o.
• le crearemos una cuenta en o.g.o si no tiene ya una.
• le daremos acceso de escritura al repositorio Git de su overlay.

Una palabra acerca de las cuentas

Ya que o.g.o está diseñada para dar cabida tanto a desarrolladores de Gentoo y a usuarios de Gentoo, no creamos cuentas a nivel de sistema 'reales' en el host de o.g.o.

3.  Trabajando con su Overlay

Introducción

Puede acceder a su overlay tan pronto como éste sea creado. Los overlays de proyecto y de desarrolladores tienen distintas URLs, así cada cual sabe qué es de quien, aparte de esto son iguales en todos los sentidos.

*No* existen restricciones de lectura en los overlays o wikis. Todos tienen completo acceso a todos los overlays y wikis. Si necesita un overlay 'secreto' o algo así, entonces o.g.o no es lo adecuado.

Accediendo a los Overlays de Proyecto

Si el overlay de su proyecto se llama 'foo', el wiki de su Trac estará aquí: http://overlays.gentoo.org/proj/foo/.

Para obtener su repositorio en Subversion, ejecute:

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

Aunque puede realizar acciones de solo lectura a través de HTTP no seguro, puede realizar todos los envíos por HTTPS. Si necesita cambiar entre modos, use:

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

Nosotros mantenemos una lista completa de los overlays de proyecto alojados en overlays.gentoo.org.

Accediendo a los Overlays de Desarrollador

Si su dirección de correo electrónico es 'foo@gentoo.org', el wiki de su sitio en Trac estará aquí: http://overlays.gentoo.org/dev/foo/.

Para obtener su repositorio en Subversion, ejecute:

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

Aunque puede realizar acciones de solo lectura a través de HTTP no seguro, puede realizar todos los envíos por HTTPS. Si necesita cambiar entre modos, use:

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

Nosotros mantenemos una lista completa de los overlays de desarrollador alojados en overlays.gentoo.org .

Empezando con Trac

Su overlay viene con Trac. Trac es un wiki, un navegador de repositorios Subversion, y un sistema de monitoreo de bugs muy popular entre los desarrolladores de código abierto.

Hemos deshabilitado el sistema de monitoreo de bugs en Trac. Use el Bugzilla de Gentoo para gestionar los bugs de su overlay.

El feed RSS de su overlay - el que se muestra en la página de inicio de o.g.o - viene de la página Timeline de Trac o del resumen GitWeb.

Comenzando con Subversion

Las ventajas de Subversion frente a CVS incluyen: versionado real de directorios, soporte completo de changeset y es mucho más fácil crear ramas en caso de necesitarlo. La principal desventaja de Subversion es que es más lento que CVS y que una verificación local de Subversion requiere mayor espacio en disco.

Si nunca ha usado Subversion, el libro en línea es una excelente forma de aprender Subversion. Puede comprarlo también en formato impreso si lo prefiere.

Aquí se muestran algunas órdenes básicas para comenzar.

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

svn status

svn add mi.ebuild

svn commit -m 'Mi actualización de historial'

Layman

Le sugerimos a los usuarios usar layman para descargar y manejar su overlay. Layman es una utilidad escrita por Gunnar Wrobel la cual le facilita a los usuarios trabajar con los overlays.

Para empezar a usar layman, mire (en inglés) la página de inicio de la documentación , las Gentoo Weekly News del 22 de mayo o lea man layman.

Sincronización Automática desde Portage

Sus paquetes en el árbol de Portage siempre están en riego de ser cambiados sin previo aviso. Los equipos de Arquitectura necesitan ser capaces de enmascarar paquetes (y arreglar problemas específicos de arquitectura), el equipo de QA (Aseguramiento de la Calidad) arregla violaciones de estándares que se han detectado, y ocasionalmente cambios en los paquetes que los desarrolladores no debían haber realizado.

Necesita asegurarse que los cambios hechos en Portage no se pierdan la próxima vez que copie sus paquetes desde su overlay de vuelta a Portage.

El equipo de PHP ha resuelto éste problema copiando automáticamente sus paquetes desde Portage de vuelta a la rama 'portage' de su overlay cada noche. Luego puede usar Subversion (o el Timeline de Trac) para ver los cambios realizados ese día.

4.  Usando git en los overlays

Inicializando su overlay

Antes subir nada, necesitará crear un repositorio git en local y añadir todos los elementos:

cd ~/my-overlay

git init
git add .
git commit -m "completar overlay"

Notar que este envío se realizó localmente, ahora el servidor entra en juego.

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

git push origin master

Fuente (en inglés): http://www.kernel.org/pub/software/scm/git/docs/tutorial.html

Obteniendo el overlay con git

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

5.  Otorgando a Otros acceso a su Overlay

Introducción

Una de las características clave de o.g.o es que la gente que no tiene acceso de escritura al árbol de paquetes del Portage de Gentoo puede tener acceso de escritura a uno o más overlays. Muchos proyectos de Gentoo han encontrado en ésta una excelente manera de entrenar y evaluar a potenciales desarrolladores de Gentoo en un entorno seguro.

Overlays de Proyecto: Otorgando accesos de escritura a Miembros del Equipo

Cualquier desarrollador listado en la página del equipo del proyecto en www.g.o puede tener acceso de escritura al overlay del equipo. El líder de proyecto puede preguntar en su nombre, o el desarrollador puede venir y preguntar por su cuenta.

Si el desarrollador no tiene una cuenta en o.g.o aún, el/ella tendrá que abrir una incidencia en bugzilla de Gentoo para que podamos crearle una.

Overlays de Proyecto: Otorgando accesos los Otros desarrolladores de Gentoo

Cualquier desarrollador de Gentoo *no* listando en la página de equipo del proyecto en www.g.o puede tener acceso de escritura al overlay del equipo. La solicitud de acceso para escritura debe venir de un miembro del equipo. No tiene porqué venir del líder de proyecto.

Si el desarrollador no tiene una cuenta en o.g.o aún, el/ella tendrá que abrir una incidencia en bugzilla de Gentoo para que podamos crearle una.

Overlays de Proyecto: Otorgando accesos de escritura a Usuarios de Gentoo

Cualquier usuario de Gentoo puede tener acceso de escritura en el overlay del equipo. La solicitud de acceso para escritura debe venir de uno de los líderes de proyecto. Puede solicitar que le demos al usuario acceso de escritura a Trac, a Subversion, o a ambos. (Nosotros asumiremos que la solicitud es para acceso de escritura a ambos, a menos que nos diga lo contrario).

No podemos aceptar una solicitud de una persona que no sea el líder del proyecto. Si su proyecto solo tiene un líder, recomendamos elegir un segundo líder. Si su único líder está AWOL (Ausente Sin Renuncia Oficial), considere elegir un sustituto :)

Si el usuario no tiene una cuenta en o.g.o aún, el/ella tendrá que abrir una incidencia en bugzilla de Gentoo para que podamos crearle una.

Overlays de Desarrollador: Otorgando accesos de escritura a Desarrolladores de Gentoo

Cualquier desarrollador de Gentoo puede tener acceso a su overlay de desarrollador. El desarrollador puede preguntarnos directamente; nosotros no le daremos acceso hasta haberlo confirmado. También puede consultarnos para dar accesos de escritura a cualquier desarrollador.

Si el desarrollador no tiene una cuenta en o.g.o aún, el/ella tendrá que abrir una incidencia en bugzilla de Gentoo para que podamos crearle una.

Overlays de Desarrollador: Otorgando accesos de escritura a Usuarios de Gentoo

Cualquier usuario de Gentoo puede tener acceso de escritura a su overlay de desarrollador. Nos deberá enviar la solicitud para este acceso a escritura. Puede solicitar que le demos al usuario accesos de escritura solo en Trac, solo en Subversion, o ambos. (Nosotros asumiremos que la solicitud es para accesos de escritura a ambos a menos que nos indique lo contrario).

No aceptaremos la solicitud de otra persona que no sea el propietario del overlay. Si ve que está dando accesos a mucha más gente, es posible que deba considerar crear un nuevo proyecto, y transferir su trabajo ahí.

Si el usuario no tiene una cuenta en o.g.o aún, el/ella tendrá que abrir una incidencia en bugzilla de Gentoo para que podamos crearle una.

6.  Accediendo al Overlay de otro

Usando un Overlay

Todos tienen acceso completo de lectura a cualquier overlay. Le recomendamos usar

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

Luego, para ver el listado de overlays, ejecute

layman -L

Para instalar un overlay, ejecute

layman -a <nombre-del-overlay>

Ahora puede instalar los paquetes del overlay.

Solicitando Accesos de Escritura

Si desea accesos de escritura a un overlay de proyecto, contacte con un miembro del equipo del proyecto, y pídale acceso. Si aprueban su solicitud, se encargarán de su acceso a escritura contactando con el equipo de Overlays.

Si desea accesos de escritura a un overlay de desarrollador, contacte con el desarrollador directamente, y pídale acceso. Si aprueba su solicitud, éste se encargará de su acceso a escritura contactando con el equipo de Overlays.

7.  Preguntas Frecuentes

Administración de o.g.o

P: ¿Cómo contacto al equipo de administración de o.g.o?

• R: Puede entrar a #gentoo-overlays en el IRC y ubicarnos ahí. La mayoría del equipo actual está en el horario Europeo.
• R: Puede enviar un correo a overlays@gentoo.org. Alguien le responderá lo más pronto posible.

P: ¿Por qué no puedo editar las listas de control de acceso directamente?

• R: (SVN) Las listas de control actualmente están implementadas en formato htpasswd. Solo el equipo de administración de o.g.o tienen acceso ssh al servidor en o.g.o.
• R: (Git) Las listas de control actualmente están instaladas en el repositorio gitosis-admin, en el cual solo pueden escribir los miembros del equipo de administración de o.g.o.

Seguridad

P: ¿Está mi overlay disponible por https?

• R: Sí, lo está.

Múltiples Overlays

P: ¿Puedo tener acceso a múltiples overlays?

• R: Sí, de una manera. Dentro su overlay, puede crear subdirectorios, y poner árboles separados de paquetes dentro los subdirectorios. Por favor, eche un vistazo al overlay del proyecto PHP para tener un ejemplo.

Importando Overlays Existentes

P: Ya tengo un overlay, y me gustaría moverlo a o.g.o. ¿Cómo puedo hacerlo?

• R: Cree un archivo tar en su repositorio de subversion, y colóquelo en cualquier lugar donde pueda descargarlo por http. Nosotros lo descargaremos e instalaremos en o.g.o.

P: Tengo un overlay, pero no usa subversion. ¿Cómo puedo moverlo a o.g.o?

• R: Pídanos crearle un nuevo overlay vacío. Puede usar 'svn import' para importar sus archivos al nuevo overlay. Perderá su historial pero eso es inevitable.
• R: Busque en Internet, y vea si existe alguna herramienta para convertir su actual sistema de control de versiones a Subversion. Si existe, úsela, y entonces podremos ayudarle a moverlo hacia o.g.o
• R: Si su software de control de versiones es usado por Trac, y puede ser usado a través de HTTP, ayúdenos a agregar el soporte para su software de control de versiones en o.g.o

Overlays "Oficiales"

P: ¿Cuándo un overlay es considerado "oficial"?

• R: Un overlay "oficial" es un overlay manejado por un proyecto de Gentoo (para overlays de proyecto) o por un desarrollador de Gentoo (overlays para desarrollador).

P: ¿Debe un overlay estar en o.g.o para ser "oficial"?

• R: No.

El contenido de este documento, a no ser que se especifique expresamente, está registrado bajo los términos de la licencia CC-BY-SA-2.5. Se aplican las Pautas de Utilización del logotipo y nombre de Gentoo.