<?xml version="1.0" encoding="utf-8"?>
<page xmlns="http://projectmallard.org/1.0/" xmlns:its="http://www.w3.org/2005/11/its" type="topic" id="versioning" xml:lang="es">

  <info>
    <link type="guide" xref="index#maintainer-guidelines"/>

    <credit type="author copyright">
      <name>Philip Withnall</name>
      <email its:translate="no">philip.withnall@collabora.co.uk</email>
      <years>2015</years>
    </credit>

    <include xmlns="http://www.w3.org/2001/XInclude" href="cc-by-sa-3-0.xml"/>

    <desc>Versionado y publicación de bibliotecas y aplicaciones</desc>
  
    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
      <mal:name>Daniel Mustieles</mal:name>
      <mal:email>daniel.mustieles@gmail.com</mal:email>
      <mal:years>2016-2020</mal:years>
    </mal:credit>
  
    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
      <mal:name>Javier Mazorra</mal:name>
      <mal:email>mazi.debian@gmail.com</mal:email>
      <mal:years>2016, 2020</mal:years>
    </mal:credit>
  </info>

  <title>Versionado</title>

  <synopsis>
    <title>Resumen</title>

    <p>La versión del módulo difiere para bibliotecas y aplicaciones: las bibliotecas necesitan una versión de libtool especificada además de su versión de paquete. Las aplicaciones solo tienen una versión de paquete.</p>

    <list>
      <item><p>Las bibliotecas y aplicaciones tienen una versión de paquete de la forma <em>major.minor.micro</em>. (<link xref="#package-versioning"/>)</p></item>
      <item><p>Las bibliotecas además tienen una versión de libtool de la forma <em>current:revision:age</em>. (<link xref="#libtool-versioning"/>)</p></item>
      <item><p>Los números de versión deben actualizarse para cada versión (usando incrementos de versión y post-versión). (<link xref="#release-process"/>)</p></item>
      <item><p>Las versiones de paquete se deben incrementar  para cambios de características o adiciones. (<link xref="#package-versioning"/>)</p></item>
      <item><p>Las versiones de Libtool deben actualizarse para cambios o adiciones de API. (<link xref="#libtool-versioning"/>)</p></item>
      <item><p>Las versiones <em>menores</em> pares/impares de paquetes se pueden usar respectivamente para versiones estables/inestables. (<link xref="#stable-unstable-versions"/>)</p></item>
    </list>
  </synopsis>

  <section id="package-versioning">
    <title>Versionado de paquetes</title>

    <p>Tanto las bibliotecas como las aplicaciones tienen una versión de paquete de la forma <em>major.minor.micro</em>.</p>

    <p>El número de versión del paquete es el que se pasa a <code>AC_INIT()</code>, y el que se suele conocer como número de versión del proyecto. Por ejemplo, el paquete Debian para una biblioteca  utilizará la versión del paquete de la biblioteca (aunque también puede incluir el numero de versión principal en el nombre del paquete para permitir <link xref="parallel-installability">instabilidad en paralelo</link>). Las versiones del paquete son actualizadas con las siguientes reglas:</p>
    <steps>
      <item><p>Si en una biblioteca se rompe <link xref="api-stability">la compatibilidad API</link>, o se hace un gran cambio a una aplicación que afecta a todo (como un rediseño de IU), incremente la  versión principal, y establezca la menor y la micro a 0.</p></item>
      <item><p>De lo contrario, si cambia o agrega una característica, o agrega cualquier API, incremente la menor y establezca la micro en 0.</p></item>
      <item><p>En caso contrario (si se hace una publicación que contenga sólo correcciones de errores y actualizaciones de traducciones), se incrementa la microversión.</p></item>
    </steps>

    <p>Tenga en cuenta que el número de versión menor debería actualizarse si se añade alguna API.</p>
  </section>

  <section id="libtool-versioning">
    <title>Versionado de Libtool</title>

    <p>Las bibliotecas tienen dos números de versión: una versión libtool que rastrea la compatibilidad ABI posterior (<link href="api-stability"/>). y una versión de paquete que rastrea los cambios de las características. Estos normalmente se incrementan sincronizadamente, pero deberían mantenerse separados porque la compatibilidad ABI posterior no está necesariamente relacionada con los cambios de las características o las correcciones de errores. Además, los dos números de versión tienen distintos significados, y no puede generarse automáticamente el uno desde el otro.</p>

    <p>Un buen resumen del versionado libtool, y las diferencias con el versionado del paquete, se da en el <link href="https://autotools.io/libtool/version.html">cazador de mitos de Autotools</link>; otro está en el <link href="http://www.gnu.org/s/libtool/manual/html_node/Updating-version-info.html">manual de libtool</link>.</p>

    <p>Para actualizar la versión libtool, siga el algoritmo dado en los comentarios debajo. Este es un fragmento de código <file>configure.ac</file> típico para configurar el versionado libtool:</p>

    <code>
# Before making a release, the LT_VERSION string should be modified. The
# string is of the form c:r:a. Follow these instructions sequentially:
#   1. If the library source code has changed at all since the last update, then
#      increment revision (‘c:r:a’ becomes ‘c:r+1:a’).
#   2. If any interfaces have been added, removed, or changed since the last
#      update, increment current, and set revision to 0.
#   3. If any interfaces have been added since the last public release, then
#      increment age.
#   4. If any interfaces have been removed or changed since the last public
#      release, then set age to 0.
AC_SUBST([LT_VERSION],[0:0:0])</code>

    <p>El siguiente fragmento de código se puede usar en un <file>Makefile.am</file> para pasar esa información de versión a libtool:</p>
    <code>my_library_la_LDFLAGS = -version-info $(LT_VERSION)</code>
  </section>

  <section id="stable-unstable-versions">
    <title>Versiones de paquetes estables e inestables</title>

    <p>La mayoría de los módulos de GNOME siguen una convención para publicaciones estables e inestables. La versión menor es par para liberaciones estables y es impar para las inestables. Por ejemplo, las versiones 3.20.* son estables, pero las versiones 3.19.* son inestables. Las versiones 3.19.* se pueden ver como entregas alfa y beta de la versión 3.20.</p>

    <p>Una nueva microversión <em>estable</em> (por ejemplo 3.20.0 → 3.20.1) no añade nuevas características, sólo actualizaciones de traducciones y corrección de errores. Por otro lado, las micropublicaciones <em>inestables</em> (por ejemplo 3.19.1 → 3.19.2) pueden añadir API, o cambiar o eliminar la API que se añadió en la micropublicación anterior en esa serie menor.</p>

    <p>La versión libtool debería actualizarse sólo para versiones de paquete estables.</p>
  </section>

  <section id="release-process">
    <title>Proceso de publicación</title>

    <p>El proceso estándar para hacer una publicación de un módulo incrementa la versión libtool (si el módulo es una biblioteca) en el momento de la entrega, por lo que incrementa el número de versión del paquete inmediatamente después (a esto se le llama un incremento posterior a la publicación).</p>

    <p>La actualización de las versiones libtool durante el tiempo de publicación significa que sólo se incrementan una vez para todos los cambios ABI de una entrega. Usar el incremento posterior a la publicación para las versiones del paquete significa que el número de versión del paquete no está desactualizado (aún igual al de la entrega anterior) durante el ciclo de desarrollo.</p>

    <p>El proceso de la publicación (basado en el <link href="https://wiki.gnome.org/MaintainersCorner/Releasing">proceso de publicación de GNOME</link>):</p>
    <steps>
      <item><p>Asegúrese de que el código está actualizado: <cmd>git pull</cmd></p></item>

      <item><p>Asegúrese de que no tiene cambios locales: <cmd>git status</cmd></p></item>
      <item><p>Si la publicación es para una versión estable del paquete, incremente el número de versión libtool en <file>configure.ac</file> (si éste existe)</p></item>
      <item><p>Añada una entrada al archivo <file>NEWS</file></p></item>
      <item>
        <p>Ejecute <cmd>./autogen.sh &amp;&amp; make &amp;&amp; make install &amp;&amp; make distcheck</cmd> y asegúrese de que termina correctamente</p>
        <list>
          <item><p>Corrija los errores que surjan, confirme esos cambios, y reincide en el paso 3</p></item>
        </list>
      </item>
      <item><p>Si <cmd>make distcheck</cmd> finaliza con «El [archivo] está listo para su distribución», ejecute <cmd>git commit -a -m «Versión de la publicación x.y.z»</cmd></p></item>
      <item>
        <p>Ejecute <cmd>git push</cmd></p>
        <list>
          <item><p>Si eso no funciona debido a que otros commits se han subido mientras tanto, ejecute <cmd>git pull</cmd> para mezclar su commit en la rama seguida de un segundo <cmd>git push</cmd>. Esta es una excepción a la directriz de GNOME de tener un histórico de Git lineal (<link xref="version-control#use-of-git"/>). Si usted prefiere tener un histórico lineal, es necesario reiniciar en el paso 1.</p></item>
        </list>
      </item>
      <item><p>Etiquete la publicación: <cmd>git tag -s x.y.z</cmd> (donde ‘x.y.z’ es el número de versión del paquete)</p></item>
      <item><p>Ejecute <cmd>git push origin x.y.z</cmd> (donde ‘x.y.z’ es el número de versión del paquete)</p></item>
    </steps>

    <p>Ahora la publicación está completa, y se puede hacer el incremento de versión posterior a la misma:</p>
    <steps>
      <item><p>Incremente el número de la versión del paquete en <file>configure.ac</file></p></item>
      <item><p>Ejecute <cmd>git commit -a -m "Post-release version increment"</cmd></p></item>
      <item><p>Ejecute <cmd>git push</cmd></p></item>
    </steps>

    <p>El archivo de paquete generado por <cmd>make distcheck</cmd> puede subirse ahora a download.gnome.org o distribuirse de otras maneras.</p>
  </section>
</page>
