             Configurar un repositorio CVS - a la manera de FreeBSD

  Stijn Hoop

   <stijn@win.tue.nl>

   Revision: 43184

   Copyright (c) 2001-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.

   2013-11-13 por hrs.
   Resumen

   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>.

   [ Split HTML / Single HTML ]

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

   Tabla de contenidos

   1. Introduccion

   2. Comienzo de la configuracion

   3. Configuracion especifica de FreeBSD

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 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

  Aviso:

   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.

  Nota:

       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.

  Nota:

       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. Nota:

       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.
