Integración con sistemas de control de errores / seguimiento de incidencias

Es muy común en el Desarrollo de Software que los cambios se refieran a un ID de error o incidencia específico. A los usuarios de los sistemas de control de errores (seguimiento de incidencias) les gustaría asociar los cambios que hacen en Subversion con un ID específico en su programa de seguimiento de incidencias. La mayoría de programas de seguimiento de incidencias proporcionan un script gancho pre-commit que parsea el mensaje de log para encontrar el ID del error con el que se asocia la confirmación. Esto es de alguna forma propenso a errores, porque se basa en el que usuario escriba el mensaje de registro de forma correcta para que el script gancho pre-commit pueda parsearlo correctamente.

TortoiseSVN puede ayudar al usuario de dos formas:

  1. Cuando el usuario introduce un mensaje de registro, puede añadirse una línea bien definida incluyendo el número de incidencia asociada a la confirmación. Esto reduce el riesgo que el usuario introduzca el número de incidencia que las herramientas de control de errores no puedan parsear correctamente.

    O TortoiseSVN puede remarcar la parte del mensaje de registro introducido que el programa de seguimiento de incidencias reconoce. De esta forma el usuario sabrá que el mensaje de registro introducido puede parsearse correctamente.

  2. Cuando el usuario navega por los mensajes de registro, TortoiseSVN crea un enlace desde cada ID de error en el mensaje de registro, que lanza el navegador con la incidencia mencionada.

Añadiendo números de incidencia en los mensajes de registro

Puede integrar una herramienta de control de errores de su elección con TortoiseSVN. Para hacerlo, necesita definir algunas propiedades, que empiezan por bugtraq:. Deben establecerse sobre las carpetas: (“Configuración del proyecto”)

Figura 4.70. El diálogo de propiedades de Bugtraq

El diálogo de propiedades de Bugtraq


When you edit any of the bugtraq properties a special property editor is used to make it easier to set appropriate values.

Hay dos formas de integrar TortoiseSVN con los programas de control de incidencias. Una se basa en simples cadenas de texto, la otra se basa en expresiones regulares. Las propiedades que se utilizan en ambos casos son:

bugtraq:url

Establezca esta propiedad a la URL de su herramienta de seguimiento de errores. Debe ser una URI debidamente codificada y debe contener %BUGID% . %BUGID% se sustituye con el número de incidencia que haya introducido. Esto permite que TortoiseSVN muestre un vínculo en el diálogo de registro, de modo que cuando usted está buscando en el registro de revisión pueda saltar directamente a la herramienta de seguimiento de errores. Usted no tiene que proporcionar esta propiedad, pero entonces TortoiseSVN sólo mostrará el número de incidencia y no el vínculo a la misma. Por ejemplo, el proyecto TortoiseSVN utiliza http://issues.tortoisesvn.net/?do=details&id =%BUGID% .

También puede utilizar URLs relativas en vez de absolutas. Esto es útil en caso que su control de incidencias esté en el mismo dominio/servidor que su repositorio. En caso que el nombre de dominio cambie alguna vez, no tendrá que ajustar la propiedad bugtraq:url. Hay dos formas de especificar una URL relativa:

Si empieza con la cadena ^/ se asume que es relativa a la raíz del repositorio. Por ejemplo, ^/../?do=details&id=%BUGID% se resolverá como http://tortoisesvn.net/?do=details&id=%BUGID% si su repositorio está en http://tortoisesvn.net/svn/trunk/.

Una URL que comience con la cadena / se asume que es relativo al nombre del servidor. Por ejemplo, /?do=details&id=%BUGID% se resolverá como http://tortoisesvn.net/?do=details&id=%BUGID% si su repositorio está localizado en cualquier parte de http://tortoisesvn.net.

bugtraq:warnifnoissue

Establezca esta propiedad a true si desea que TortoiseSVN le avise cuando deje en blanco el campo de texto del número de incidencia. Los valores válidos son true/false. Si no se define, se supone false.

Número de incidencia en caja de texto

En el caso simple, TortoiseSVN muestra al usuario un campo de entrada separado donde se puede introducir un ID del error. En ese caso se añade una línea adicional al final o al principio del mensaje de registro que el usuario introduce.

bugtraq:message

Esta propiedad activa el sistema de control de errores en el modo campo de entrada. Si se establece esta propiedad, TortoiseSVN le preguntará por el número de incidencia cuando confirme sus cambios. Se utiliza para añadir una línea al final del mensaje de registro. Debe contener %BUGID%, que se reemplaza por el número de la incidencia al confirmar. Esto asegura que su registro de confirmación contiene una referencia al número de incidencia que siempre está en un formato consistente y que puede ser parseado por su herramienta de control de errores para asociar el número de incidencia con una confirmación en concreto. Un ejemplo que puede que le sirva es Incidencia : %BUGID%, pero esto depende de su herramienta.

bugtraq:label

Éste es el texto que TortoiseSVN muestra en el diálogo de confirmar para etiquetar el cuadro de texto en el que introduce el número de incidencia. Si no se establece, aparecerá Bug-ID / Nº-Incid.:. Tenga en cuenta, sin embargo, que la ventana no se cambiará de tamaño para acomodar esta etiqueta, por lo que debería mantener el tamaño de la etiqueta en menos de 20-25 caracteres.

bugtraq:number

Si se establece a true sólo se permitirán números en el campo de número de incidencia. La coma es una excepción, para que pueda introducir varios números separados por comas. Los valores válidos son true/false. Si no se define, se asumirá true.

bugtraq:append

Esta propiedad define si el ID del error se añade (true) al final del mensaje de registro o se inserta (false) al inicio del mensaje de registro. Los valores válidos son true/false. Si no se define, se asume true, para que los proyectos ya existentes no se rompan.

Números de incidencia utilizando expresiones regulares

En el caso de utilizar expresiones regulares, TortoiseSVN no muestra un campo de entrada separado sino que marca, del mensaje de registro que el usuario introduce, la parte que reconoce el programa de seguimiento de incidencias. Esto se realiza mientras el usuario introduce el mensaje de registro. ¡Esto también significa que el ID del error puede introducirse en cualquier parte dentro de un mensaje de registro! Este método es mucho más flexible, y es el que se utiliza en el propio proyecto TortoiseSVN.

bugtraq:logregex

Esta propiedad activa el sistema de control de errores en modo Regex. Contiene una expresión regular, o dos (en líneas separadas).

Si se dan dos expresiones, la primera expresión se utiliza como un pre-filtro para encontrar expresiones que contengan identificadores de incidencias. La segunda expresión se utiliza para extraer los identificadores individuales desde los resultados de la primera expresión regular. Esto le permite utilizar una lista de identificadores de incidencias y expresiones en lenguaje natural, si así lo desea. Por ejemplo puede arreglar varias incidencias e incluir una cadena como esta: Este cambio resuelve las incidencias #23, #24 y #25 .

Si desea capturar identificadores de incidencias utilizados como en la expresión anterior dentro de un mensaje de registro, puede utilizar las siguientes cadenas de expresiones regulares, que son los utilizados en el proyecto TortoiseSVN: [Ii]ssues?:?(\s*(,|and)?\s*#\d+)+ y (\d+)

La primera expresión extrae incidencias #23, #24 y #25 de entre el resto del mensaje de registro. La segunda expresión regular extrae los números decimales individuales desde la salida de la primera expresión regular, por lo que devolverá 23, 24 y 25 para utilizarlos como identificadores de incidencias.

Profundizando en la primera expresión regular un poco, debe empezar con la palabra incidencia, posiblemente empezando por mayúscula. Opcionalmente puede ir seguida de una s (más de una incidencia) y opcionalmente dos puntos. A esto le sigue uno o más grupos, cada uno empezando por cero o más espacios en blanco, una coma opcional o y y más espacios opcionales. Finalmente, hay un # obligatorio y un número decimal obligatorio.

Si sólo se establece una expresión, entonces los identificadores individuales de incidencias deben concordar con los grupos de la expresión regular. Por ejemplo: [Ii]ncidencia(?:s)? #?(\d+) Este método se necesita por algunos gestores de incidencias, por ejemplo trac, pero la expresión regular es más dificil de construir. Le recomendamos que sólo utilice este método si la documentación de su gestor de incidencias se lo indica.

If you are unfamiliar with regular expressions, take a look at the introduction at https://en.wikipedia.org/wiki/Regular_expression, and the online documentation and tutorial at http://www.regular-expressions.info/.

It's not always easy to get the regex right so to help out there is a test dialog built into the bugtraq properties dialog. Click on the button to the right of the edit boxes to bring it up. Here you can enter some test text, and change each regex to see the results. If the regex is invalid the edit box background changes to red.

Si se establecen las dos propiedades bugtraq:message y bugtraq:logregex, logregex tiene preferencia.

Sugerencia

¡Incluso si no tiene un programa de seguimiento de incidencias con un gancho pre-commit parseando sus mensajes de log, puede seguir utilizando ésto para convertir las incidencias mencionadas en su mensajes de registro en vínculos!

E incluso si no necesita los vínculos, los números de incidencias se muestran como una columna separada en el diálogo de registro, facilitándole la búsqueda de los cambios que se refieran a una incidencia en concreto.

Algunas propiedades tsvn: necesitan un valor true/false (verdadero/falso). TortoiseSVN también entiende yes (sí) como un sinónimo de true y no como un sinónimo de false.

Estableciendo las propiedades en las carpetas

Esas propiedades deben activarse en carpetas del sistema a trabajar. Cuando confirmas un archivo o carpeta, las propiedades son leídas de esa carpeta. Si no se encuentran las propiedades ahí, TortoiseSVN buscara en orden ascendente en el arbol de carpetas, para encontrarlas, hasta que encuentre una carpeta fuera del control de versiones, o la raíz del árbol (por ejemplo: C:\) es encontrada. Si estas seguro que cada usuario hace check out de y no de alguna sub-carpeta, entonces sera suficiente si se ponen las propiedades en . Si no estas seguro, entonces se deberán poner las propiedades recursivamente en cada sub-carpeta. Una propiedad mas profunda en la jerarquía del proyecto, tendrá preferencia sobre niveles mas altos (mas cercanos a trunk/).

As of version 1.8, TortoiseSVN and Subversion use so called inherited properties, which means a property that is set on a folder is automatically also implicitly set on all subfolders. So there's no need to set the properties on all folders anymore but only on the root folder.

Excusivamente para las propiedades de proyecto , por ejemplo: tsvn:, bugtraq: and webviewer:, puede utilizar la casilla Recursivo para establecer la propiedad en todas las subcarpetas de la jerarquía, sin establecerla en todos los archivos.

Cuando añade nuevas subcarpetas a una copia de trabajo utilizando TortoiseSVN, cualquier propiedad de proyecto presente en la carpeta padre se añadirá también automáticamente a la nueva carpeta hija.

Sin información de seguimiento de incidencias desde el navegador de repositorios

Because the issue tracker integration depends upon accessing Subversion properties, you will only see the results when using a checked out working copy. Fetching properties remotely is a slow operation, so you will not see this feature in action from the repo browser unless you started the repo browser from your working copy. If you started the repo browser by entering the URL of the repository you won't see this feature.

Por la misma razón, las propiedades del proyecto no se propagarán automáticamente cuando un se añada una carpeta hija usando el navegador de repositorios.

This issue tracker integration is not restricted to TortoiseSVN; it can be used with any Subversion client. For more information, read the full Issue Tracker Integration Specification in the TortoiseSVN source repository. (“Licencia” explains how to access the repository.)

Obteniendo información desde el gestor de incidencias

La sección anterior se refiere a cómo añadir información de incidencias en los mensajes de registros. Pero, ¿y si lo que necesita es obtener información desde el gestor de incidencias? El diálogo de confirmación tiene un interfaz COM que le permite la integración de un programa externo que pueda hablar con su gestor de incidencias. Típicamente, querrá interrogar al gestor para obtener una lista de incidencias abiertas que tenga asignadas, para que pueda seleccionar las incidencias de las que se va a hacer cargo en esta confirmación.

Any such interface is of course highly specific to your issue tracker system, so we cannot provide this part, and describing how to create such a program is beyond the scope of this manual. The interface definition and sample plugins in C# and C++/ATL can be obtained from the contrib folder in the TortoiseSVN repository. (“Licencia” explains how to access the repository.) A summary of the API is also given in Capítulo 7, Interfaz IBugtraqProvider. Another (working) example plugin in C# is Gurtle which implements the required COM interface to interact with the Google Code issue tracker.

Por poner un ejemplo ilustrativo, supongamos que el administrador de su sistema le ha proporcionado un plugin de gestor de incidencias que ya ha instalado, y que ha preparado algunas de sus copias de trabajo para que utilicen el plugin en el diálogo de configuración de TortoiseSVN. Cuando abra la ventana de confirmación desde una copia de trabajo que tenga el plugin asignado, verá un nuevo botón en la parte superior del diálogo.

Figura 4.71. Diálogo de ejemplo de la interacción con el gestor de incidencias

Diálogo de ejemplo de la interacción con el gestor de incidencias


En este ejemplo, puede seleccionar una o más incidencias abiertas. El plugin podrá entonces generar texto específicamente formateado para añadirlo a su mensaje de registro.