<!--
     El proyecto de documentaci&oacute;n de FreeBSD

     $FreeBSD$
-->

<chapter id="policies">
  <title>Gu&iacute;as y pol&iacute;ticas del &aacute;rbol de c&oacute;digo fuente</title>
  
  <para><emphasis>Contribuci&oacute;n de &a.phk;.</emphasis></para>
  
  <para>Este cap&iacute;tulo documenta la pol&iacute;tica por la que se rige el
    &aacute;rbol de c&oacute;digo fuente de FreeBSD.</para>
  
  <sect1 id="policies-maintainer">
    <title><makevar>MAINTAINER</makevar> en Makefiles</title>
    
    <para>Junio 1996.</para>
    
    <para>Si una parte en particular de la distribuci&oacute;n FreeBSD es mantenida por 
    una persona o grupo de personas, pueden comunicar este hecho al mundo a&ntilde;adiendo 
    esta l&iacute;nea
	
      <programlisting>
MAINTAINER= email-addresses</programlisting>
	
      a los <filename>Makefile</filename>s que cubren esta parte del &aacute;rbol de 
      c&oacute;digo fuente.</para>
	
    <para>La sem&aacute;ntica de es como sigue:</para>
    
    <para>El mantenedor posee y es responsable de ese c&oacute;digo. Esto significa que 
    &eacute;l es responsable de arreglar errores y responder reportes de problemas relacionados 
    con esa parte del c&oacute;digo, y en el caso de contribuci&oacute;n de software, de revisar 
    nuevas versiones, seg&uacute;n sea necesario.</para>
	
    <para>Los cambios en directorios que tienen un mantenedor definido deber&aacute;n ser 
    enviados al mantenedor para ser revisados antes de ser incluidos.
    S&oacute;lo si el mantenedor no responde durante un periodo de tiempo inaceptable, a 
    varios mensajes, ser&aacute; aceptable incluir cambios sin la revisi&oacute;n del 
    mantenedor. Sin embargo, se sugiere que los cambios sean revisados por alguien m&aacute;s 
    si es posible.</para>
	
    <para>No es aceptable, por supuesto, a&ntilde;adir una persona o grupo como mantenedor a 
    menos que est&eacute;n de acuerdo en asumir esta tarea. Por otro lado, no tiene 
    porqu&eacute; ser un committer, pudiendo ser f&aacute;cilmente un grupo de personas.</para>
  </sect1>
  
  <sect1>
    <title>Software de Contribuci&oacute;n</title>
    
    <para><emphasis>Contribucion de &a.phk; y &a.obrien;.</emphasis></para>
    
    <para>Junio 1996.</para>
    
    <para>Algunas partes de la distribuci&oacute;n de FreeBSD consisten en software
      que est&aacute; siendo mantenido activamente fuera del proyecto FreeBSD. Por razones 
      hist&oacute;ricas, llamamos a esto software <emphasis>de contribuci&oacute;n</emphasis>.
      Algunos ejemplos son perl, gcc y patch.</para>
	
    <para>En los &uacute;ltimos dos a&ntilde;os, se han usado diferentes m&eacute;todos para 
      tratar con este tipo de software y todos tienen algunas ventajas e inconvenientes. No 
      ha emergido ning&uacute;n claro ganador.</para>
	
    <para>Ya que este es el caso, despu&eacute;s de algo de debate uno de estos
      m&eacute;todos ha sido seleccionado como el m&eacute;todo &ldquo;oficial&rdquo;
      y ser&aacute; requerido para futuras importaciones de este tipo de software.
      M&aacute;s a&uacute;n, se sugiere firmemente que el software de contribuci&oacute;n existente
      converja con este modelo en el futuro, ya que tiene ventajas significativas
      sobre el antiguo m&eacute;todo, incluyendo la habilidad de obtener f&aacute;cilmente 
      diferencias relativas a la versi&oacute;n &ldquo;oficial&rdquo; del fuente por todos 
      (a&uacute;n sin acceso cvs). Esto har&aacute; significativamente mas f&aacute;cil el 
      devolver cambios a los desarrolladores primarios del software de contribuci&oacute;n.</para>
	
    <para>Finalmente, sin embargo, quedan las personas que est&aacute;n haciendo el
      trabajo. Si usar este modelo es particularmente incompatible con el paquete con el cual 
      se trata, se pueden conceder excepciones a esta regla solo con la aprobaci&oacute;n del 
      core team y con el consenso general de los otros desarrolladores. La habilidad de mantener 
      el paquete en el futuro ser&aacute; un asunto clave en las decisiones.</para>

    <note>
      <para>Debido a algunas desafortunadas limitaciones de dise&ntilde;o con el formato de 
        archivo RCS y el uso de las ramas "vendors" con el CVS, son
        <emphasis>fuertemente desaprobados</emphasis> cambios cosm&eacute;ticos, triviales y/o 
        menores en archivos que est&eacute;n siendo seguidos por la rama "vendor". 
        Los "arreglos de sintaxis" est&aacute;n incluidos expl&iacute;citamente aqu&iacute; 
        bajo la categor&iacute;a "cosm&eacute;ticos" y deben ser evitados en archivos con
        revisi&oacute;n 1.1.x.x.  El impacto que puede tener la modificaci&oacute;n de un 
        s&oacute;lo car&aacute;cter en el repositorio puede ser bastante dram&aacute;tico.</para>
    </note>
    
    <para>El lenguaje de programaci&oacute;n <application>Tcl</application> ser&aacute; usado 
      como un ejemplo sobre como este modelo trabaja:</para>
	
    <para><filename>src/contrib/tcl</filename> contiene los fuentes distribuidos
      por los mantenedores de este programa. Las partes que no son enteramente
      aplicables a FreeBSD pueden ser eliminadas. En el caso del Tcl, los subdirectorios
      <filename>mac</filename>, <filename>win</filename> y <filename>compat</filename> fueron 
      eliminados antes de la importaci&oacute;n</para>
	
    <para><filename>src/lib/libtcl</filename> contiene s&oacute;lo un <filename>Makefile</filename>
      estilo bmake que usa las reglas est&aacute;ndar <filename>bsd.lib.mk</filename> makefile
      para producir la librer&iacute;a e instalar la documentaci&oacute;n.</para>
	
    <para><filename>src/usr.bin/tclsh</filename> contiene s&oacute;lo un
      <filename>Makefile</filename> estilo bmake que producir&aacute; e instalar&aacute;
      el programa <command>tclsh</command> y sus p&aacute;ginas man asociadas usando las 
      reglas est&aacute;ndar <filename>bsd.prog.mk</filename></para>
	
    <para><filename>src/tools/tools/tcl_bmake</filename> contiene un par de shell scripts que 
      pueden ser de ayuda cuando el software tcl necesita actualizaci&oacute;n. Estos no son 
      parte integral o de instalaci&oacute;n del software.</para>
	
    <para>Lo importante aqu&iacute; es que el directorio
      <filename>src/contrib/tcl</filename> se crea de acuerdo a las reglas:
      se supone que debe contener las fuentes tal y como se distribuyen (en una rama vendor
      adecuada del CVS y sin expansi&oacute;n de claves RCS) con tan pocos cambios 
      espec&iacute;ficos para FreeBSD como sea posible. La herramienta "easy-import" 
      (importaci&oacute;n f&aacute;cil) en freefall ayudar&aacute; haciendo la 
      importaci&oacute;n, pero si hay dudas acerca de como hacerlo, es imperativo que se pregunte 
      primero y no hacerlo esperando que &ldquo;funcione&rdquo;.  El CVS no perdona accidentes de 
      importaci&oacute;n y se requiere un gran esfuerzo para arreglar grandes errores.</para>
    
    <para>Debido a las limitaciones de dise&ntilde;o previamente mencionadas de las
      ramas "vendor" del CVS, se requiere que los parches &ldquo;oficiales&rdquo;
      del vendedor sean aplicados a los fuentes originales de distribuci&oacute;n y el
      resultado reimportado otra vez en la rama vendor correspondiente. Los parches oficiales
      nunca deben ser usados en la versi&oacute;n disponible en el CVS de FreeBSD e integrados, 
      ya que esto destruye la coherencia de la rama vendor y hace que la importaci&oacute;n de
      futuras versiones sea m&aacute;s complicada por la aparici&oacute;n de conflictos.
    </para>
	
    <para>Ya que muchos paquetes contienen archivos cuya intenci&oacute;n es la
      compatibilidad con otras arquitecturas y ambientes distintos a FreeBSD,
      es permisible eliminar partes del &aacute;rbol de distribuci&oacute;n que no son de
      inter&eacute;s para FreeBSD con el fin de ahorrar espacio. Los archivos que
      contienen notas de copyright y notas de la versi&oacute;n, informaci&oacute;n en algo 
      aplicable a los archivos que quedan <emphasis>no</emphasis> deber&aacute;n ser eliminados.
    </para>
    
    <para>Si parece m&aacute;s f&aacute;cil, los <command>bmake</command>
      <filename>Makefile</filename>s pueden ser producidos automaticamente desde el &aacute;rbol 
      de distribuci&oacute;n por alguna utilidad, algo que podr&iacute;a hacer 
      aun m&aacute;s f&aacute;cil el actualizar a una nueva versi&oacute;n. Si esto es hecho,
      aseg&uacute;rese de revisar tales utilidades (como sea necesario) en el directorio 
      <filename>src/tools</filename> junto con el mismo port para que est&eacute; disponible 
      para los futuros mantenedores.</para>
	
    <para>En el nivel de directorio <filename>src/contrib/tcl</filename>
      debe ser a&ntilde;dido un archivo llamado <filename>FREEBSD-upgrade</filename> 
      debiendo presentar cosas como:</para>
    
    <itemizedlist>
      <listitem>
        <para>Qu&eacute; archivos se han dejado fuera de la importaci&oacute;n</para>
      </listitem>
      
      <listitem>
        <para>De donde fue obtenida la distribuci&oacute;n original y/o el
         servidor oficial principal.</para>
      </listitem>
      
      <listitem>
        <para>D&oacute;nde enviar parches a los autores originales</para>
      </listitem>
      
      <listitem>
        <para>Una visi&oacute;n general de los cambios espec&iacute;ficos que se han hecho
          para FreeBSD.</para>
      </listitem>
    </itemizedlist>
    
    <para>Sin embargo, por favor no importar <filename>FREEBSD-upgrade 
      (actualizaci&oacute;n)</filename> con los fuentes de contribuci&oacute;n. En su lugar,
       usar <command>cvs add FREEBSD-upgrade ; cvs ci</command> despu&eacute;s del prompt 
       inicial. M&aacute;s abajo existe un ejemplo de sintaxis de 
       <filename>src/contrib/cpio</filename>:</para>
	
    <programlisting>
Este directorio contiene c&oacute;digos fuente virgen de los archivos originales de
distribuci&oacute;n en una rama "vendor". No tratar, bajo ninguna circunstancia,
de actualizar los archivos en este directorio con parches y un cvs commit.
Nuevas versiones o versiones oficiales de parches deben ser importadas.
Por favor recuerdar importar con "-ko" para prevenir que el CVS corrompa
el Id del RCS de algun vendor.

Para la importaci&oacute;n del GNU cpio 2.4.2, se eliminaron los siguientes archivos:

        INSTALL         cpio.info       mkdir.c             
        Makefile.in     cpio.texi       mkinstalldirs

Para actualizar a una versi&oacute;n m&aacute;s nueva de cpio, cuando est&eacute; disponible:
        1. Descomprimir la nueva versi&oacute;n en un directorio vac&iacute;o.
           [No hacer NINGUN cambio a los archivos.]

        2. Eliminar los archivos listados arriba y cualquier otro que no se relacione
           con FreeBSD.

        3. Usar el comando:
                cvs import -ko -m 'Virgin import of GNU cpio v&lt;version&gt;' \
                        src/contrib/cpio GNU cpio_&lt;version&gt;

           Por ejemplo, para importar la versi&oacute;n 2.4.2, usar:
                cvs import -ko -m 'Virgin import of GNU v2.4.2' \
                        src/contrib/cpio GNU cpio_2_4_2

        4. Seguir las instrucciones del paso 3 para resolver cualquier conflicto entre 
           cambios locales de FreeBSD y la nueva versi&oacute;n.

NO desviarse, bajo ninguna circunstancia, de este procedimiento.

Para hacer cambios locales al cpio, simplemente aplicar el patch y commit a la rama
principal (tambi&eacute;n conocida como HEAD).  Nunca hacer cambios locales
en la rama GNU.

Todos los cambios locales deber&iacute;an ser enviados a "cpio@gnu.ai.mit.edu" para
su inclusi&oacute;n en la nueva versi&oacute;n release.

obrien@FreeBSD.org - 30 March 1997</programlisting>
  </sect1>

  <sect1 id="policies-encumbered">
    <title>Archivos "adicionales" (encumbered)</title>

    <para>Ocasionalmente podr&iacute;a ser necesario incluir un archivo "adicional" en el 
      c&oacute;digo fuente de FreeBSD. Por ejemplo, si un dispositivo requiere que una 
      peque&ntilde;a pieza de c&oacute;digo binario sea cargada antes de que el dispositivo 
      funcione, y no tenemos los fuentes de ese c&oacute;digo, entonces se dice que el archivo 
      binario es "encumbered".
      Las siguientes pol&iacute;ticas se aplican al incluir archivos encumbered en
      en el &aacute;rbol fuente FreeBSD.</para>

    <orderedlist>
      <listitem>
        <para>Cualquier archivo que sea interpretado o ejecutado por la CPU del
          sistema y no en formato fuente es encumbered.</para>
      </listitem>

      <listitem>
        <para>Cualquier archivo con una licencia m&aacute;s restrictiva que BSD o GNU
          es encumbered.</para>
      </listitem>

      <listitem>
        <para>Un archivo que contiene datos binarios descargables para que el
          hardware lo use no es encumbered, a menos que (1) o (2) se apliquen
          a &eacute;l. Debe ser guardado en un formato ASCII neutral a la arquitectura
          (se recomienda file2c o uuencodeado).</para>
      </listitem>

      <listitem>
        <para>Cualquier archivo encumbered requiere aprobaci&oacute;n espec&iacute;fica del
          <link linkend="staff-core">Core team</link> antes de ser a&ntilde;adido al
          repositorio CVS.</para>
      </listitem>

      <listitem>
        <para>Los archivos encumbered van en <filename>src/contrib</filename>
          o <filename>src/sys/contrib</filename>.</para>
      </listitem>

      <listitem>
        <para>El m&oacute;dulo entero deber&iacute;a ser mantenido en su conjunto. No hay excusa en
          separarlo, a menos que haya intercambio de c&oacute;digo con c&oacute;digo no encumbered.
       </para>
      </listitem>

      <listitem>
        <para>Los archivos objeto son nombrados 
          <filename><replaceable>arch</replaceable>/<replaceable>filename</replaceable>.o.uu></filename>
          .</para>
      </listitem>

      <listitem>
        <para>Archivos del Kernel:</para>

        <orderedlist>
          <listitem>
            <para>Siempre deben ser referenciados en <filename>conf/files.*</filename> (para 
            simplicidad del build).</para>
	  </listitem>

          <listitem>
            <para>Siempre deber&iacute;a estar en <filename>LINT</filename>, pero el <link 
              linkend="staff-core">Core team</link> decide caso por caso si
              deber&iacute;a ser comentado o no. El <link
              linkend="staff-core">Core team</link> puede, por supuesto, cambiar
              su opini&oacute;n m&aacute;s adelante.</para>
          </listitem>

          <listitem>
            <para>El <link linkend="staff-who">Ingeniero de Release</link>
              decide si va o no a la release.</para>
          </listitem>
        </orderedlist>
      </listitem>

      <listitem>
        <para>Archivos de usuario:</para>

        <orderedlist>
          <listitem>
            <para>El <link linkend="staff-core">Core team</link> decide si
              el c&oacute;digo deber&iacute;a ser parte de <command>make world</command>.</para>
          </listitem>
         
          <listitem>
            <para>El <link linkend="staff-who">Ingeniero de la Release</link>
              decide si va a la release.</para>
          </listitem>
        </orderedlist>
      </listitem>
    </orderedlist>
  </sect1>
  
  <sect1 id="policies-shlib">
    <title>Librer&iacute;as compartidas</title>
    
    <para><emphasis>Contribuido por &a.asami;, &a.peter;, y &a.obrien;  9 
      Diciembre 1996.</emphasis></para>
	
    <para>Si se est&aacute; a&ntilde;adiendo soporte para librer&iacute;as compartidas a un puerto u
      otra pieza de software que no tiene uno, los n&uacute;meros de versi&oacute;n deben
      seguir estas reglas. Generalmente, los n&uacute;meros resultantes no tendr&aacute;n nada
      que ver con la versi&oacute;n release del software.</para>
	
    <para>Los tres principios de la construcci&oacute;n de librer&iacute;as compartidas son:</para>

    <itemizedlist>
      <listitem>
        <para>Comenzando desde <literal>1.0</literal></para>
      </listitem>
      
      <listitem>
        <para>Si hay un cambio que sea compatible con versiones anteriores,
          eliminar el n&uacute;mero menor</para>
      </listitem>
      
      <listitem>
        <para>Si hay un cambio incompatible, quitar el n&uacute;mero mayor</para>
      </listitem>
    </itemizedlist>
    
    <para>Por ejemplo, funciones a&ntilde;adidas y soluci&oacute; de errores resultan en la 
      eliminaci&oacute;n del numero de versi&oacute;n menor, mientras que las funciones borradas,
      sintaxis cambiada de llamada de funci&oacute;n, etc, forzar&aacute;n que el n&uacute;mero
      de versi&oacute;n mayor cambie.</para>
    
    <para>Usar los n&uacute;meros de versi&oacute;n de la forma mayor.menor
      (<replaceable>x</replaceable>.<replaceable>y</replaceable>).  Nuestro
      lincador din&aacute;mico no gestiona correctamente n&uacute;meros de versi&oacute;n
      de la forma <replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable>
    . Cualquier n&uacute;mero de versi&oacute;n despu&eacute;s de <replaceable>y</replaceable>
      (es decir, el tercer d&iacute;gito) es totalmente ignorado cuando
      se comparan n&uacute;meros de versi&oacute;n de librer&iacute;as compartidas
      para decidir con que librer&iacute;a enlazar. Dadas 2 librer&iacute;as compartidas
      que difieren  s&oacute;lo en la  &ldquo;micro&rdquo; revisi&oacute;n,
      <command>ld.so</command> enlazar&aacute; con la mas alta. Es decir:
      si se enlaza con <filename>libfoo.so.3.3.3</filename>, el lincador
      s&oacute;lo reconoce <literal>3.3</literal> en los encabezados,
      y enlazar&aacute; con cualquiera que comience con <replaceable>libfoo.so.3</replaceable>.
      <replaceable>(cualquier cosa &gt;=3)</replaceable>.<replaceable>(el m&aacute;s alto 
      disponible)</replaceable>.</para>
      <note>
        <para><command>ld.so</command> siempre usar&aacute; la revisi&oacute;n 
          &ldquo;menor&rdquo; m&aacute;s alta. Es decir: usar&aacute;
          <filename>libc.so.2.2</filename> en preferencia a
          <filename>libc.so.2.0</filename>, aun si el programa estaba
          inicialmente enlazado con <filename>libc.so.2.0</filename>.</para>
      </note>
    
    <para>Para librer&iacute;as no portables, es tambi&eacute;n nuestra pol&iacute;tica cambiar
      el n&uacute;mero de versi&oacute;n de librer&iacute;a compartida solo una vez entre releases.
      Cuando se hace un cambio a una librer&iacute;a del sistema que requiere
      que se quite el n&uacute;mero de versi&oacute;n, revisar los logs commit del 
      <filename>Makefile</filename>. Es responsabilidad del miembro del commit asegurarse de que 
      el primer cambio desde la release har&aacute; que se actualice el n&uacute;mero de versi&oacute;n
      de la librer&iacute;a compartida en el <filename>Makefile</filename>, y cualquier 
      subsecuente cambio no lo har&aacute;.</para>
  </sect1>
</chapter>

<!-- 
     Local Variables:
     mode: sgml
     sgml-declaration: "../chapter.decl"
     sgml-indent-data: t
     sgml-omittag: nil
     sgml-always-quote-attributes: t
     sgml-parent-document: ("../book.sgml" "part" "chapter")
     End:
-->
