Como generar con Maven un histórico de cambios del proyecto

Creación: 20-08-2007

Índice de contenidos

• 1.Introducción
• 2. Entorno
• 3. El fichero changes.xml
• 4. Cambios en nuestro pom.xml
• 5. Modificando el site.xml
• 6. Conclusiones
• 7. Sobre el autor

1. Introducción

Siempre resulta muy interesante tener un informe con los cambios que se van realizando en nuestro proyecto. El típico ‘changelog’ o ‘history’ o similar donde se reflejan las nuevas
funcionalidades o correcciones que se han realizado en cada versión.

En Maven podemos encontrar el plugin ‘maven-changes-plugin’
(http://maven.apache.org/plugins/maven-changes-plugin/) que nos permite realizar esta tarea.

Este plugin montará un informe en el ‘site’ del proyecto con la información que tengamos en el fichero src/changes/changes.xml

Para mantener este fichero podemos elegir entre:

• Mantenerlo a mano.
• Integrarlo con el JIRA. El plugin ya viene preparado para esto
• Hacer algún programita o proceso intermedio que saque la información de nuestro repositorio de incidencias y la convierta al formato esperado por maven-changes-plugin.

Evidentemente la primera opción es la peor de todas ya que requiere más trabajo por nuestra parte. Yo os recomiendo hacer el esfuerzo para integrarlo con vuestro sistema de gestión de incidencias, ya que este esfuerzo se vera recompensado.

2. Entorno

El tutorial está escrito usando el siguiente entorno:

• Hardware: Portátil Asus G1 (Core 2 Duo a 2.1 GHz, 2048 MB RAM, 120 GB HD).
• Sistema Operativo: GNU / Linux, Debian (unstable), Kernel 2.6.22, KDE 3.5
• Java 1.5
• Maven 2.0.7

3. El fichero changes.xml

Ya hemos dicho que este fichero debe estar en src/changes/ (en las últimas versiones del plugin se puede configurar donde lo queremos tener).

Este fichero tendrá un aspecto como esté (este ejemplo está sacado directamente de la documentación de maven-changes-plugin):

    Johnny R. Ruiz III

        Added additional documentation on how to configure the plugin.

        Enable retrieving component-specific issues.

        The element type " link " must be terminated by the matching end-tag.
        Deleted the erroneous code.

        Uploaded documentation on how to use the plugin.

Veamos que significa cada elemento:

• <release>
  • version (obligatorio): nombre de la versión en la que han ocurrido los cambios. Para cada cambio habrá un elemento action anidado.
  • date (obligatorio): fecha en la que se ha publicado la versión. Es un texto libre, no requiere ningún formato especial.
  • description: Una descripción opcional para esta versión. Se mostrará en el reumen al principio del informe.
• <action>
  • dev (obligatorio): nombre del desarrollador que ha subido el cambio al repositorio de versiones (por ejemplo al Subversion). Debe coincidir con el id de uno de los desarrolladores descritos en el elemento <developers> del pom.xml.
  • type (obligatorio): tipo del cambio. Puede tomar los siguientes valores:
    • add: algo que se ha añadido nueva en esta versión.
    • fix: algo que se ha arreglado en esta versión.
    • remove: algo que se ha eliminado en esta versión.
    • update: algo que se ha actualizado en esta versión.
  • issue: Identificador de nuestro sistema de gestión de incidencias (por ejemplo el id del Bugzilla). Aunque este atributo es opcional, es muy recomendable ya que se generará un enlace en el informe que nos permitirá saltar directamente al bug en nuestro sistema de gestión de incidencias.
  • due-to: Permite especificar el nombre de la persona que ha hecho el cambio. La diferencia con el atributo dev es que due-to refleja quien ha hecho el cambio, y dev quien lo ha subido al repositorio de versiones. Es decir, los dev son los que tienen permiso de escritura en el repositorio de versiones, mientras que los due-to no tienen permisos de escritura, así que tienen que hacer un parche y mandárselo a un dev para que este lo suba al repositorio.
  • due-to-email: Correo electrónico del dev.

El aspecto del informe generado con este XML será algo como:

4. Cambios en nuestro pom.xml

Para que el maven-changes-plugin funcione correctamente vamos a hacer los siguientes cambios en el pom.xml.

Primero vamos a asegurarnos que tenemos declarado el sistema de gestión de incidencias:

...

    Bugzilla
    http://servidor/bugzilla/

...

Esta información la va a usar el plugin para crear los enlaces de los cambios en el changes.xml con el sistema de gestión de incidencias. Mucho ojo al escribir la URL porque esta tiene que terminar en ‘/’. Si no ponéis la ‘/’ del final no funcionará correctamente.

Ahora vamos a declarar la lista de desarrolladores:

...

        alex
        Alejandro Pérez García
        alejandropg@autentia.com
        Autentia Real Business Solutions
        
Home


    ...

...

Como ya hemos dicho antes, el atributo dev del elemento <action> en el fichero changes.xml, debe coincidir con el elemento <id>.

Ahora vamos a indicarle a Maven que queremos que nos genere el informe:

...

            org.apache.maven.plugins
            maven-changes-plugin

                %URL%/show_bug.cgi?id=%ISSUE%

                        changes-report

...

Cabe destacar como con el elemento <issueLinkTemplate> le podemos indicar como tiene que componer la URL para apuntar al bug en nuestro sistema de gestión de incidencias.

• %URL% representa la URL definida anteriormente con el elemento <issueManagement>. Fijaros como después de %URL% hemos puesto una ‘/’. Como la barra ya estaba en issueManagement, podría parecer que estamos poniéndola 2 veces, pero no, todo lo contrario, si aquí no ponemos la ‘/’, tampoco funcionará.
• %ISSUE% es el id del bug que hemos introducido en el fichero changes.xml en el atributo issue del elemento <action>.

Con esto, cada vez que generemos el site del proyecto se nos generará el informe con los cambios.

5. Modificando el site.xml

Simplemente recordar que para que en nuestro site aparezcan correctamente los informes (javadoc, taglist, changes, …), deberemos añadir la variable de Velocity ${reports} en el fichero src/site/site.xml podría quedar algo como:

${reports}

Con esto nos aparecerá en el menú del site (el menú de la izquierda) la lista con todos los informes que hayamos indicado que queremos generar.

6. Conclusiones

Ya hemos comentado en otros tutoriales la importancia de la correcta gestión de las incidencias. Esto lo debemos hacer siempre a través de una aplicación estilo Bugzilla o JIRA o Trac o Scarab o … Y de hecho, el fichero changes.xml se nos queda muy corto para nuestros propósitos.

No deberíamos usar el fichero changes.xml para llevar la gestión de las incidencias; pero si es una muy buena forma para documentar en nuestro proyecto los cambios que se producen en cada versión. Por esto es esencial (como proponíamos al principio del tutorial) integrar nuestro sistema de gestión de incidencia con el el fichero changes.xml, de forma que este se genere de forma automática.

7. Sobre el autor

Alejandro Pérez García, Ingeniero en Informática (especialidad de Ingeniería del Software)

Socio fundador de Autentia (Formación, Consultoría, Desarrollo de sistemas transaccionales)

mailto:alejandropg@autentia.com

Autentia Real Business Solutions S.L. – «Soporte a Desarrollo»

http://www.autentia.com