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 elementoaction
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>
delpom.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 atributodev
es quedue-to
refleja quien ha hecho el cambio, ydev
quien lo ha subido al repositorio de versiones. Es decir, losdev
son los que tienen permiso de escritura en el repositorio de versiones, mientras que losdue-to
no tienen permisos de escritura, así que tienen que hacer un parche y mandárselo a undev
para que este lo suba al repositorio. -
due-to-email
: Correo electrónico deldev
.
-
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 SolutionsHome... ...
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 enissueManagement
, 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 ficherochanges.xml
en el atributoissue
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»
Muy bueno el tutorial, como todos los del autor