El arte de escribir commits en Git

25/08/2019 | Git | 0 comentarios

El mensaje del commit es la parte más importante en un repositorio, si esta redactado correctamente te ayudará a entender los cambios en tu proyecto.

En Git los commits son los registros de los cambios hechos en un proyecto, sirven para tener un historial ordenado de todos las modificaciones hechas en un proyecto.

¿Cuándo crear commits?

El objetivo de un commit es ayudar a entender los cambios de un proyecto e incluso a recuperar parte del trabajo pasado, esto se logra asociando una tarea a un commit, esta técnica se llama atomic commits y se puede resumir en:

Cada commit debe estar asociado a una tarea específica de modo que se pueda deshacer la tarea sin afectar otras tareas.

Una tarea puede ser: una nueva funcionalidad, una corrección, una mejora o un cambio, incluso una sub-tarea de otra tarea más grande.

Con esto podemos proponer algunas recomendaciones:

  • Un commit debe estar asociado a una tarea o sub-tarea específica.
  • No se deben agrupar varias tareas en un sólo commit.
  • Sólo se deben hacer commits de tareas terminadas, no tareas parciales o incompletas.
  • El commit debe incluir todos los archivos modificados en la tarea.
  • El commit sólo debe afectar la tarea asociada y no afectar otras tareas.

El mensaje del commit

Analizando un commit se puede observar que esta formado por: un identificador único, los datos del autor, la fecha de registro, un listado con los cambios detallados por cada archivo y un mensaje que lo agrega el usuario.

Esta información permite conocer: quién y cuándo se realizó un cambio, que cambios y en que archivos se realizaron los cambios. Lo que no dice esta información es la razón del cambio, para ello existe el mensaje del commit:

El mensaje del commit debe describir los motivos por los cuales se realizaron los cambios.

Entonces si redactamos correctamente los mensajes de los commits será posible entender el cómo y el por qué de los cambios del proyecto.

Formato del commit

Si la tarea es sencilla puedes utilizar una sola línea:

Resumen de la tarea con máximo 50 caracteres

Si utilizas un herramienta para seguimiento de tareas puedes usar el formato:

#issue | Resumen de la tarea con máximo 50 caracteres

Si la tarea es compleja o cuando el encabezado no es suficiente para describir la tareas puedes utilizar el formato completo:


Encabezado del commit con máximo 50 caracteres

Cuerpo del commit con la descripción detallada de la tarea
y las razones por las que se realizan los cambios. Se debe 
separar del encabezado con una línea en blanco y contiene
información adicional de la lógica y/o servicios utilizados 
en la tarea (opcional). 

Referencias: #issue (opcional)

Para el mensaje completo se deben seguir las siguientes recomendaciones:

  • El encabezado es obligatorio y debe estar limitado a 50 caracteres.
  • El encabezado debe comenzar con mayusculas y no debe terminar con punto.
  • El encabezado debe estar expresado en modo imperativo, es decir como una orden.
  • El cuerpo del commit debe estar separado por una línea en blanco.
  • El cuerpo debe estar limitado a 72 caracteres por línea.
  • El cuerpo debe explicar el por qué de los cambios en lugar del como.

El encabezado es utilizado para visualizar el listado de commits y generalmente se recortan cuando a un máximo de 50 caracteres por ello se recomienda evitar sobrepasar este límite. Debe estar escrito el modo imperativo o como una orden para mantener la homogeneidad.

Conclusiones

Los commits redactados correctamente ayudan a entender los cambios de un proyecto y si están agrupados correctamente recuperar tareas sin afectar a otras tareas. Entonces sigue las reglas propuestas y mejorarás los mensajes de tus commits.

Referencias

Envíar Comentario

En este sitio los comentarios se publican previa aprobación del equipo de Kodetop. Evita los comentarios ofensivos, obscenos o publicitarios. Si deseas publicar código fuente puedes hacerlo entre las etiquedas <pre></pre>