         Configurar un repositorio CVS - a la manera de FreeBSD

  Stijn Hoop

   <stijn@win.tue.nl>

   $FreeBSD: doc/es_ES.ISO8859-1/articles/cvs-freebsd/article.sgml,v
   1.4 2007/11/08 21:49:10 carvay Exp $

   Copyright (c) 2001, 2002, 2003 Stijn Hoop

   FreeBSD is a registered trademark of the FreeBSD Foundation.

   Many of the designations used by manufacturers and sellers to
   distinguish their products are claimed as trademarks. Where those
   designations appear in this document, and the FreeBSD Project was
   aware of the trademark claim, the designations have been followed
   by the "(TM)" or the "(R)" symbol.

   Este articulo describe los pasos que di para configurar un
   repositorio CVS con los mismos "scripts" usados por el proyecto
   FreeBSD en su configuracion. Tienen algunas ventajas frente a las
   demas configuraciones de CVS, por ejemplo una gestion mas eficaz
   de los accesos a los arboles de codigo y la creacion de mensajes
   de correo electronico por cada commit.

   Traduccion de Jesus R. Camou <jcamou@FreeBSD.org>.

     --------------------------------------------------------------

1 Introduccion

   Muchos de los proyectos de software de codigo abierto usan CVS
   como su sistema de gestion de codigo. Aunque CVS es bastante bueno
   para esto tiene sus inconvenientes y sus flaquezas. Un ejemplo de
   esto es el compartir un arbol de codigo con otros desarrolladores,
   lo cual puede convertirse rapidamente en una pesadilla para la
   administracion del sistema, especialmente si se desea proteger del
   acceso indiscriminado ciertas partes del arbol.

   FreeBSD es uno de los proyectos que usan CVS. Tambien cuenta con
   una gran cantidad de desarrolladores alrededor del mundo. Ellos
   mismos desarrollaron algunos "scripts" para hacer del manejo del
   repositorio una tarea mas facil. Recientemente estos "scripts"
   fueron revisados por Josef Karthauser <joe@FreeBSD.org> para
   facilitar su uso en otros proyectos. Este articulo muestra uno de
   los metodos para usar estos nuevos "scripts".

   Si quiere sacar verdadero partido de la informacion que se le
   brinda en este articulo debe tener familiaridad con metodos
   basicos para realizar operaciones CVS.

     --------------------------------------------------------------

2 Comienzo de la configuracion

     Warning: Es preferible que realice estos procedimientos en un
     repositorio de prueba vacio y podamos asi asegurarnos de que
     entiende todas las consecuencias. Como siempre, asegurese de
     tener respaldos recientes.

     --------------------------------------------------------------

  2.1 Inicio del repositorio

   Lo primero a hacer al configurar un nuevo repositorio es decirle a
   CVS que lo inicie:

 % cvs -d ruta-al-repositorio
          init

   Esto le indica a CVS que cree el directorio administrativo
   CVSROOT, donde se albergaran todas las configuraciones.

     --------------------------------------------------------------

  2.2 El grupo del repositorio

   Ahora vamos a crear al grupo dueno del repositorio. Todos los
   "committers" necesitan estar en este grupo, para de esta manera
   poder escribir en el repositorio. Asumiremos el grupo ncvs por
   defecto de FreeBSD.

 # pw groupadd ncvs
        

   A continuacion, es necesario usar chown(8) en el directorio para
   ajustar los permisos al grupo recion agregado:

 # chown -R :ncvs
        
         path-a-su-repositorio

   Esto asegura que nadie podra escribir en el repositorio sin los
   permisos de grupo adecuados.

     --------------------------------------------------------------

  2.3 Obtencion del codigo

   Ahora es necesario obtener el directorio CVSROOT del repositorio
   de FreeBSD. Puede hacerse muy facilmente desde una replica del CVS
   anonimo de FreeBSD. Para mas informacion consulte el capitulo
   correspondiente del Handbook. Asumiremos que el codigo esta en
   CVSROOT-freebsd en el directorio actual.

     --------------------------------------------------------------

  2.4 Copia de los "scripts" de FreeBSD

   El siguiente paso consiste en copiar el codigo de FreeBSD sito en
   CVSROOT a nuestro repositorio. Si esta familiarizado con CVS ,
   puede pensar que se puede realizar importando los "scripts", lo
   que deberia permitirle sincronizar posteriores versiones muy
   facilmente. No es asi, CVS tiene una deficiencia en este aspecto:
   al intentar importar codigo al directorio CVSROOT no se
   actualizaran los ficheros administrativos necesarios. Para hacer
   que esto suceda es necesario ejecutar "checkin" en cada uno de
   ellos despues de importarlos, perdiendo asi el valor de cvs
   import. En consecuencia el metodo recomendado para este cometido
   es sencillamente copiar los "scripts".

   No importa en realidad si no encuentra demasiado sentido al
   parrafo anterior, el resultado sera el mismo. Simplemente haga
   "check out" de su CVSROOT y copie los ficheros de FreeBSD a su
   copia local:

 % cvs -d         ruta-a-su-repositorio  checkout CVSROOT
         % cd CVSROOT
         % cp ../CVSROOT-freebsd/* .
         % cvs add *

   Tenga en cuenta que probablemente recibira advertencias acerca de
   directorios no copiados; es normal que suceda pero no debe usted
   preocuparse porque estos no son necesarios.

     --------------------------------------------------------------

  2.5 Los "scripts"

   Ahora ya cuenta con una copia exacta en su directorio de trabajo
   de los "scripts" que FreeBSD usa en la gestion de su repositorio.
   He aqui una descripcion del cometido de cada uno de ellos.

     * access - este fichero no se usa en la configuracion por
       defecto. Se usa en la configuracion del proyecto FreeBSD, el
       cual controla el acceso al repositorio. Puede borrar este
       fichero si no quiere usarlo en su configuracion.

     * avail - este fichero controla el acceso al repositorio. Dentro
       del mismo es posible especificar grupos de personas
       autorizadas para el acceso al repositorio, asi como commits no
       autorizados en uno o mas directorios dados. Debera editarlo
       para que contenga los grupos y directorios que se usaran en su
       repositorio.

     * cfg.pm - este fichero se encarga de analizar su configuracion
       y provee la configuracion por defecto. No debera usted cambiar
       nada en este fichero. Si va a hacer cambios su configuracion
       deberan ir en cfg_local.pm.

     * cfg_local.pm - contiene todos los parametros configurables del
       sistema. Debera configurar todo tipo de cosas en este fichero,
       tales como el envio por correo electronico de los mensajes de
       commit, desde que "hosts" pueden hacer commits los usuarios,
       etc. Mas informacion mas adelante en el texto.

     * checkoutlist - este fichero lista todos los ficheros bajo
       control de CVS en este directorio, aparte de aquellos estandar
       creados por cvs init. Debera editar este para borrar algunos
       ficheros especificos del proyecto FreeBSD.

     * commit_prep.pl - este " script" se encarga de realizar algunas
       comprobaciones previas a cada commit segun las modificaciones
       hechas o o no en su version de cfg_local.pm. No deberia
       modificar este "script".

     * commitcheck - este "script" es invocado directamente por CVS.
       En primer lugar comprueba que la "committer" tenga acceso a
       una parte especifica del arbol usando cvs_acls.pl, para
       despues ejecutar commit_prep.pl, mediante el que efectuara las
       comprobaciones de rigor previas a cada commit. Si todo ha ido
       bien CVS permitira que el commit tenga lugar. No deberia tocar
       este fichero.

     * commitinfo - este fichero es usado por CVS para determinar que
       "script" se debera ejecutar antes de hacer el commit, en este
       caso commitcheck. Tampoco deberia tener que modificar este
       fichero.

     * config - el fichero de configuracion del repositorio. Deberia
       editarlo si es necesario aunque la mayoria de los
       administradores lo dejan tal y como viene por defecto. Dispone
       de mas informacion sobre las opciones que pueden declararse en
       el en el manual de CVS.

     * cvs_acls.pl - este "script" determina la identidad de los
       "committers", asi como si tiene permitido acceder al arbol.
       Esta basado en el fichero avail. No deberia tener que
       modificar este fichero.

     * cvsignore - este fichero especifica los ficheros que CVS no
       debe incluir en el repositorio. Puede editarlo a su gusto.
       Para mas informacion sobre fichero consulte el manual de CVS.

     * cvswrappers - CVS usa este fichero para activar o desactivar
       la expansion de la expansion de palabras clave o si el fichero
       debe ser considerado binario. Este fichero puede editarse
       segun necesidades. Para mas informacion sobre este fichero
       consulte el manual de CVS. Tenga en cuenta que las opciones -t
       y -f no funcionan correctamente con CVS cliente/servidor.

     * edithook - este fichero ya no se usa, aunque se mantenga por
       razones historicas. Este fichero puede borrarse con total
       tranquilidad sin miedo de perjudicar la configuracion.

     * editinfo - CVS usa este fichero en las sobreescrituras de
       edicion. FreeBSD no usa esta funcion ya que el analisis de
       mensajes de "log" se hace mediante verifymsg y logcheck. Esto
       se debe a que editinfo no funciona correctamente con commits
       remotos ni con aquellos que usan las opciones -m o -F. No
       deberia tener que modificar este fichero.

     * exclude - este fichero lista expresiones regulares usadas por
       commit_prep.pl para determinar ficheros que no puedan contener
       cabeceras de revision. En la configuracion que se usa en
       FreeBSD todos los ficheros bajo control de revision necesitan
       tener lo que se llama una cabecera de revision ($FreeBSD$).
       Todos los ficheros que aparezcan en alguna de las lineas de
       exclude no pasan por dicha revision. Incluya en este fichero
       entradas para aquellos ficheros que no puedan tener una
       cabecera de revision. Si va a instalar los "scripts" CVSROOT/
       es un firme candidato para figurar en este fichero.

     * log_accum.pl - este es el "script" encargado de obtener el
       mensaje de "log" que genera logcheck y anadirlo a un fichero
       de "log" en el repositorio para que pueda disponerse de
       respaldos en caso de necesidad. Tambien gestiona el envio de
       un correo electronico a la direccion que el administrador
       declare (en cfg_local.pm). loginfo se encarga de conectar
       log_accum.pl con CVS. No deberia tener que modificar este
       fichero.

     * logcheck - este fichero revisa el mensaje de commit
       proporcionado por el "committer" e intenta esterilizarlo,
       valga la expresion. Este fichero conecta con CVS via verifymsg
       . Tampoco deberia tener que modificar este fichero.

         Note: Este "script" depende de un hack de CVS propio de
         FreeBSD: esta version lee el mensaje de "log" despues de que
         este "script" lo haya modificado. La version estandar de CVS
         no hace esto, lo que hace a logcheck incapaz de limpiar los
         mensajes de "log", aunque es capaz de comprobar que este
         sintacticamente correcto. CVS 1.11.2 puede configurarse para
         tener el mismo comportamiento que la version de FreeBSD
         activando RereadLogAfterVerify=always en el fichero config.

     * loginfo - este fichero es usado por CVS para controlar donde
       se envia la informacion de "log"; aqui es donde log_accum.pl
       entra en escena. No deberia tener que modificar este fichero.

     * modules - este fichero mantiene su significado tradicional en
       CVS. Debera borrar los modulos propios de FreeBSD de la
       version que vaya a usar. Puede editarlo a su gusto. Tiene mas
       informacion acerca de este fichero en el manual de CVS.

     * notify - CVS usa este fichero en caso de que alguien ponga un
       fichero en modo "watch". No se usa en el repositorio de
       FreeBSD y puede editarse cuanto se desee. Tiene mas
       informacion acerca de este fichero en el manual de CVS.

     * options - este fichero se usa especificamente en la version de
       CVS de FreeBSD, asi como en la version de Debian. Contiene una
       palabra clave para expander cabeceras de revision. Tendra que
       modificar este fichero y escribir la misma palabra que haya
       declarado en cfg_local.pm (si es que quiere usar esa
       caracteristica, claro esta; el valor por defecto es FreeBSD)

     * rcsinfo - este fichero mapea directorios en el repositorio
       para aplicar una plantilla como rcstemplate. Por defecto
       FreeBSD usa una plantilla para el repositorio. Es posible
       anadir otras plantillas si se estima conveniente.

     * tagcheck - este fichero controla el acceso a marcar "tags"
       (etiquetas) en el repositorio. La version por defecto en
       FreeBSD no admite etiquetas con nombre RELENG* debido al
       proceso de ingenieria de releases. Puede editar este fichero
       segun sus necesidades.

     * taginfo - este fichero mapea operaciones de etiquetado en los
       directorios del repositorio, cosa necesaria en el
       funcionamiento habitual de "scripts" de control como tagcheck.
       No deberia tener que modificar este fichero.

     * unwrap - este "script" puede ser usado para alterar el estado
       de ficheros binarios en una forma opuesta a como lo hace
       cvswrappers, descrito al principio de esta lista. No se usa en
       la configuracion que funciona hoy dia en FreeBSD porque no
       funciona correctamente con commits remotos. No deberia tener
       que modificar este fichero.

     * verifymsg - este fichero mapea directorios del repositorio con
       "scripts" encargados del proceso posterior de mensajes de
       commit en ficheros de "log", por ejemplo logcheck. No deberia
       verse en la necesidad de modificar este fichero.

     * wrap - este script puede usarse para poner ficheros binarios
       bajo el efecto de cvswrappers (descrito al principio de esta
       lista) en cada "checkin". No se usa en la configuracion que
       mantiene el proyecto FreeBSD porque no funciona correctamente
       con commits remotos. No deberia tener que modificar este
       fichero.

     --------------------------------------------------------------

  2.6 Modificacion de los "scripts"

   El siguiente paso es configurar los "scripts" para que se adapten
   a sus necesidades. Tendra que revisar todos y cada uno de los
   ficheros en el directorio y hacer sus propios cambios y
   configuraciones. Seguramente tendra que editar los siguientes
   ficheros:

    1. Si no desea usar los "scripts" de la configuracion especifica
       de FreeBSD puede borrar tranquilamente el fichero access:

 % cvs rm -f access
          

    2. Editar avail para que contenga los diferentes directorios del
       repositorio en los cuales quiera controlar el acceso.
       Asegurese de mantener la linea avail||CVSROOT, si no lo hace
       no podri realizar el siguiente paso.

       Otra de las opciones que puede anadir a este fichero es el
       grupo de "committers". Por defecto FreeBSD usa el fichero
       access para listar todos sus "committers" pero se puede usar
       cualquier fichero que se desee. Tambien es posible agregar
       grupos si se desea (la sintaxis esta declarada en la primera
       parte de cvs_acls.pl ).

    3. Edite cfg_local.pm para que contenga las opciones deseadas.
       Seguramente le seran de gran interes las siguientes
       configuraciones:

          * %TEMPLATE_HEADERS - estos son procesados por los
            "scripts" de "log" y se insertan bajo el correo de commit
            si es que existen. Puede que quiera borrar las entradas
            PR y MFC after; y claro, puede agregar las suyas.

          * $MAIL_BRANCH_HDR - puede anadir una cabecera en cada
            correo de commit en la que se detalle la rama ("branch")
            en la que se ha hecho el commit. Defina la cabecera segun
            su configuracion y necesidades o dejelo vacio si no desea
            usar dicha cabecera.

          * @COMMIT_HOSTS - defina este valor si desea listar los
            "hosts" desde los que sera posible hacer commits.

          * $MAILADDRS - defina este como la direccion del
            administrador o de alguna lista donde reciban los correos
            de commit.

          * @LOG_FILE_MAP - cambie este valor como desee. Cada
            expresion regular (regexp) se compara en el directorio
            del commit, y el mensaje de log del commit se guarda en
            el subdirectorio commitlogs en el nombre de fichero
            mencionado.

          * $COMMITCHECK_EXTRA - si no desea usar las comprobaciones
            de acceso especificas de FreeBSD deberia borrar la
            definicion de $COMMITCHECK_EXTRA de este fichero.

         Note: Cambiar el parametro $IDHEADER es algo que solo puede
         asegurarse que funcionara en FreeBSD; depende de las
         modificaciones especificas de CVS hechas por FreeBSD.

       Revise cfg.pm y compruebe si alguna de las opciones puede
       modificarse, aunque los cambios propuestos en los parrafos
       anteriores son bastante razonables.
    4. Seguramente quiera borrar las lineas del principio de exclude
       (las que contienen ^ports/, entre otras), puesto que son
       especificas de FreeBSD. Ademas de esto comente las lineas que
       empiecen con ^CVSROOT/ y agregue una linea solo con ^CVSROOT/.
       Despues de que "wrapper" sea instalado puede anadir su
       cabecera a los ficheros en el directorio CVSROOT y restaurar
       estas lineas; por lo pronto solo estaran estorbaran en el
       momento que quiera hacer un commit.

    5. Edite modules y borre todo lo relacionado con FreeBSD. Anada
       sus propios modulos si lo cree necesario.

    6. Note: Este paso es solo necesario si usted ha declarado un
         valor a $IDHEADER en cfg_local.pm (que solo funciona usando
         la version de CVS modificada por FreeBSD).

       Edite options y asegurese de que la etiqueta declarada sea la
       misma que en cfg_local.pm. Simplemente cambie la etiqueta
       FreeBSD por la suya.

    7. Edite rcstemplate para que contenga las mismas palabras clave
       (o "keywords") declaradas en cfg_local.pm.

    8. Puede borrar (este paso es opcional) las comprobaciones
       realizadas por tagcheck. Puede simplemente anadir exit 0 al
       principio del fichero para deshabilitar todas las
       comprobaciones que hace sobre las etiquetas.

    9. El ultimo paso antes de terminar es asegurarse de que sea
       posible guardar de modo seguro los mensajes de commit. Por
       defecto se guardan en el propio repositorio, en el
       subdirectorio commitlogs del directorio CVSROOT. Este
       directorio debe crearse del siguiente modo:

 % mkdir commitlogs
             % cvs add commitlogs
            

   Despues de una revision cuidadosa debe hacer los commits
   necesarios con sus cambios. Asegurese de haber activado su acceso
   al directorio CVSROOT en su avail antes de intentarlo. Una vez
   haya comprobado que todo es correcto puede hacer lo siguiente:

 % cvs commit -m '- Commit
         para iniciar los scripts de FreeBSD'
        

     --------------------------------------------------------------

  2.7 Prueba de la configuracion

   Ahora ya esta listo para la primera prueba: un commit forzado al
   fichero avail para asegurarnos de que todo funciona como se
   espera.

 % cvs commit -f -m'Commit
         forzado para probar los nuevos scripts en CVSROOT'
         avail

   Si todo ha funcionado !felicidades! Dispone de una configuracion
   de los "scripts" de FreeBSD en su repositorio. Si CVS le da algun
   tipo de error en algo revise todo de nuevo y asegurese de que
   todos los pasos se hayan hecho correctamente.

     --------------------------------------------------------------

3 Configuracion especifica de FreeBSD

   El proyecto FreeBSD utliza una configuracion ligeramente diferente
   de la descrita; se usan los ficheros de configuracion del
   subdirectorio freebsd en CVSROOT. El proyecto lo hace de esta
   manera debido al gran numero de committers y a que todos y todas
   han de estar en el mismo grupo. Un "wrapper" simple fue escrito
   para poder asegurar que los usuarios tengan permisos correctos
   para poder hacer hacer commits; este "wrapper" establece el id del
   grupo al que el repositorio tiene.

   Si su repositorio lo necesita tambien los pasos para hacerlo estan
   documentados mas adelante. Pero antes de nada veamos una
   descripcion de los ficheros involucrados.

     --------------------------------------------------------------

  3.1 Ficheros usados en la configuracion de FreeBSD

     * access - este fichero controla la informacion de acceso. Se
       debe editar este fichero e incluir a todos los miembros del
       proyecto.

     * freebsd/cvswrap.c - este es el codigo de CVS wrapper que va a
       ser necesario instalar para hacer que todos los chequeos de
       acceso funcionen. Mas informacion sobre el mas adelante en el
       texto. Deberia editar las rutas de las macros ACCESS y REALCVS
       para que se correspondan con su configuracion.

     * freebsd/mailsend.c - este fichero es necesario para la
       configuracion de la lista de correo de FreeBSD. No debera
       tocar este fichero.

     --------------------------------------------------------------

  3.2 El procedimiento

    1. Edite el fichero access para que solo contenga su nombre de
       usuario.

    2. Edite el fichero cvswrap.c para que contenga la ruta correcta
       de su configuracion. Se define con una macro llamada ACCESS.
       Debera cambiar tambien el lugar del binario de cvs si no
       coincide con el de su sistema. cvswrap.c esta pensado para
       sustituir al comando cvs del sistema, que pasara a ser
       /usr/bin/ncvs .

       Mi copia de cvswrap.c tiene lo siguiente:

 #define ACCESS "/local/cvsroot/CVSROOT/access"
 #define REALCVS "/usr/bin/ncvs"

    3. Instalaremos despues wrapper para asegurarnos de que se haya
       convertido en el grupo correcto al hacer el commit. Tiene el
       codigo fuente en cvswrap.c en su CVSROOT.

       Tendra que compilar el codigo una vez haya incluido en el las
       rutas correctas:

 % cc -o cvs cvswrap.c
            

       E instalelos (necesitara ejecutar este paso como root):

 # mv /usr/bin/cvs /usr/bin/ncvs
            
             # mv cvs /usr/bin/cvs
             # chown root:ncvs
             /usr/bin/cvs /usr/bin/ncvs
             # chmod o-rw /usr/bin/ncvs
             #  chmod u-w,g+s /usr/bin/cvs
            

       Esto instala wrapper como el comando cvs por defecto; asi nos
       aseguramos de que cualquiera que quiera usar el repositorio
       necesita tener los niveles de acceso correctos.

    4. Ahora ya puede eliminar a todos los usuarios del grupo del
       repositorio. Todo control de acceso lo hara a partir de ahora
       wrapper y este wrapper establecera el grupo de acceso
       correcto.

     --------------------------------------------------------------

  3.3 Prueba de la configuracion

   Su wrapper deberia estar listo. Deberia probarlo, claro esta,
   haciendo un commit forzado al fichero access:

 % cvs commit -f -m 'Commit
         forzado para probar los nuevos scripts en CVSROOT'
         access

   Si algo falla asegurese de que todos los pasos arriba descritos se
   han realizado correctamente.

     --------------------------------------------------------------

          Puede descargar este y muchos otros documentos desde
                ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/.

Si tiene dudas sobre FreeBSD consulte la documentacion antes de escribir
                  a la lista <questions@FreeBSD.org>.
    Envie sus preguntas sobre la documentacion a <doc@FreeBSD.org>.
