avargas

Yo he visto a varias personas iniciarse con los sistemas de control de versiones, preguntan algunas cosas, como ¿por qué usarlos?, ¿qué ventajas tienen?, hacen pequeñas encuestas entre la gente que conocen sobre cuál sistema prefieren y por qué, hasta que se deciden por uno, lo instalan, cacharrean, etc y llega el momento del primer commit y la pregunta siempre es la misma: ¿Qué escribo en el mensaje del commit?,¿importa?,¿puedo escribir cualquier cosa?

La respuesta es sí, sí puede ecribir lo que sea, pero sí importa lo que escribe, he recogido algunas opiniones personales nacidas desde la experiencia sobre las mejores prácticas a la hora de escribir un mensaje para un commit.

¿Por qué importan los logs de los sistemas de control de versiones?

La razón por la que estos mensajes importan, es que un sistema de control de versiones, adicional a las ventajas que entrega siendo una mini máquina del tiempo para ir atrás en la historia del código, es un medio de comunicación entre los desarrolladores de una aplicación, e incluso entre el equipo de desarrollo y la comunidad de usuarios/desarrolladores que al rededor del producto existe.

Los usuarios avanzados pueden leer los logs para ver que ha cambiado, el equipo de relaciones públicas puede crear comunicados mas acertados con esta información, incluso si hay betatesters pueden usarse los logs como una forma de darles a conocer los cambios realizados que necesitan ser probados.

En algunos proyectos (no podría decir que todos), el changelog, ese documento que es actualizado con cada nueva versión del producto es creado a partir de la salida de los logs del sistema de control de versiones, imagense el trabajo que implicaría tener que reconstruir ese changelog revisando uno a uno cada commit.

¿Cómo sé si lo estoy haciendo bien?

Haga este ejercicio: puede ud, solo mirando los logs (svn log o git log o lo que sea) decir que nuevas características y correcciones a errores a tenido su aplicación en los últimos, digamos, 6 meses ? (sin hacer trampa y mirar el código), si la respuesta es no, o definitivamente tiene que consultar los diffs para ver lo que un commit incluye es casi seguro que no lo esta haciendo bien.

¿Cómo puedo mejorarlos?

La solución es simple y solo requiere de disciplina, acordar con los demás participantes del proyecto un estandar para los mensajes de los commits, por naturaleza cada commit puede decir quien hizo el cambio, cuando lo hizo, y que archivos modificó, el resto de la información importante debe ser añadida como parte del mensaje, entre esta información faltante están:

El número del ticket asociado a este commit: los sistemas de gestión de proyectos que se integran con sistemas de control de versiones, son capaces de leer estos mensajes en busca de números de ticket y palabras claves que activan alguna acción en el workflow; por ejemplo en redmine si se usa #1234 se crea automáticamente un comentario en el ticket (ticket 1234 en este caso), que vincula el ticket con el commit, cualquier persona que tenga acceso al ticket 1234 verá que hay un commit al respecto, también puede usar "closes #1234 " para cerrar el ticket con solo hacer el commit; esto es cierto para muchos sistemas de administración de proyectos.

Tipo de operación realizada: puede usar un pequeño estandar, puede iniciar cada commit con uno de los siguientes caracteres para indicar el tipo de operación; # -> para correcciones, + -> para nuevas caracteristicas o nuevos archivos(nuevo código en general), - -> para la eliminación de caracteristicas o eliminación de código en general y ! -> para anotaciones o cosas que no quepan en las otras categorías; revisando un poco por ahí parece ser que el equipo Joomla usa algo similar, en cuanto otros proyectos como Wordpress o Drupal parecen no usar ninguno.

algún texto explicativo sobre la razón de existencia del commit, incluso puede ser el título del commit en el sistema de gestión de tickets (en caso de que sean bien elaborados)

Un ejemplo:

+ implementando #1234 sistema de autenticación oauth de twitter, falta pulir la interfaz.
# corrigiendo error del commit anterior que produce cuentas de usuario duplicadas

Un ejemplo de mensajes poco útiles:

autenticación con twitter
mas cambios de twitter

En general, darse una pasada por los changelogs de diferentes proyectos y/o sus sistemas de control de versiones puede darle algunas buenas ideas sobre como crear mensajes de calidad para sus commits y mejorar la comunicación con su equipo de desarollo.