Icono del sitio Alexander Andrade

Plantilla para escribir mejores mensajes de commits

El código es comunicación y no solo es neceario hacerlo bien si eres un desarrollador o un QA Automator o SDET (Software Engineer in Test o Ingeniero de Desarrollo de Software especialista en Pruebas). Por su parte, también es importante tener una buena gestión del sistema de control de versiones, este cuenta la historia paso-a-paso de la evolución del código. Por lo anterior, es necesario estandarizar la manera como hacemos los commits, para garantizar que estamos dejando para la posteridad la bitácora de cambios que se han realizado y nuevos integrantes del equipo, o nuevos equipos puedan tener una guía documentada.

El objetivo de este artículo es dejarte SIN excusas para no definir una convención de mensajes de commits para tu equipo. ¡Voy a explicar las razones por las que debes definir una convención de mensajes de commit de git y compartir instrucciones detalladas para ayudarte a mover esta tarea de tu lista de “tareas pendientes” a “terminada” en unos pocos y simples pasos!

¿Por qué utilizar una convención de mensajes de commit?

Un historial de mensajes de commit bien organizado conduce a mensajes más legibles que son fáciles de seguir cuando se revisa el historial del proyecto.

Mejor colaboración

Aprovecha al máximo las utilidades de git

$ git log es un comando poderoso, pero de repente, navegar a través de la salida del registro (log) se convierte en una misión posible.

Implementar una convención de mensajes de commits también te ayudará a utilizar adecuadamente otros comandos de git como git blamegit revertgit rebasegit shortlog y otros subcomandos.

Identificar los cambios de Versionado Semántico

El Versionado Semántico (SemVer) es un conjunto simple de reglas y requerimientos que dictan cómo asignar e incrementar los números de las versiones del software. Dado un número de versión MAYOR.MENOR.PARCHE, se incrementa:

La convención de mensajes de commits va de la mano con el SemVer, al describir las características, las correcciones y los cambios importantes realizados en los mensajes de commits

Mas adelante se dan una serie de tips y ejemplos para correlacionar el SemVer y la definición de commits propuesta en este artículo.

Clave para escribir mejores mensajes de commit

La parte más importante de un mensaje de commit es que debe ser claro significativo. A la larga, escribir buenos mensajes de commits muestra lo colaborador que eres.

Definición de una convención de mensaje de commit

Primero que nada, todos los commits deben estar en inglés, así como el código, nombres de variables y hasta comentarios de código (que deberían evitarse, de acuerdo con las recomendaciones de Código Limpio por Robert C. Martin, también conocido por su nombre en inglés: Clean Code). A continuación, esta sería la convención propuesta:

type(scope o alcance): subject (asunto)
<body><footer>

El commit contiene los siguientes elementos estructurales, para comunicar la intención a los consumidores:

Tipos (type) de commits

Alcance (scope) del commit (opcional)

Un alcance DEBE consistir en un sustantivo (recuerda: siempre en inglés) que describa una sección del código base afectada por los cambios (o simplemente el nombre de la épica) entre paréntesis. Ejemplo:

feat (claims)
fix (orders)

Asunto (subject) del commit

Breve descripción de los cambios aplicados.

Ejemplos:

feat(claims): add claims detail page
fix(orders): validation of custom specification

Cuerpo (body) del commit (opcional)

Normalmente no se requeriría, por eso es opcional, pues el asunto (subject) del commit debería ser suficiente. No obstante, utiliza el cuerpo (body) para explicar, en inglés, qué cambios ha realizado y por qué los hizo, cuando se requiera un poco mas de contexto.

Ejemplo:

refactor!: drop support for Node 6
BREAKING CHANGE: refactor to use JavaScript features not available in Node 6.

Pie de página (footer) del commit (opcional)

Utilice esta sección para hacer referencia a problemas afectados por los cambios de código o comentar a otros desarrolladores o evaluadores. Ejemplo:

fix(orders): correct minor typos in code
See the issue for details on typos fixed.
Reviewed-by: @John Doe
Refs #133

Si quiere resolver problemas automáticamente en Jira al subir nuevo código (Resolve issues automatically when users push code): para vincular el commit a un problema (issue) desde un mensaje de commit, incluya un par <comando> <issue> en algún lugar de su mensaje de commit, por ejemplo, close #658reopen #459, etc. – el comando especificado se ejecutará en el issue etiquetado.

Consejos SemVer

Para correlacionar el SemVer con la definición de commits planteada, se puede seguir las siguientes instrucciones:

El curioso caso de revertir un commit:

Echemos un vistazo a otro mensaje de commit:

feat(lang): add polish language
Reviewed-by: @John Doe
Refs #133

Ahora, por alguna razón, debe eliminar la compatibilidad con el lenguaje polaco; todo lo que tiene que hacer es revertir (revert) al commit anterior, como se menciona a continuación:

Revert "feat(lang): add polish language"
Refs: 676104e, a215868

¡Voila! Escribir mejores mensajes de commit no solo mantiene estructurado su historial de commitssino que también le permite aprovechar al máximo las utilidades de git .

En este vínculo podrá encontrar una plantilla de GitHub lista para usar que puede importar fácilmente en sus repositorios y personalizar según sea necesario.

Mejores prácticas de commits para Git 

Haga commits atómicos: pequeños y de un solo propósito

Para una gestión adecuada del código fuente y una mejor limpieza, un commit debe ser un contenedor para los cambios relacionados. Por ejemplo, corregir dos errores diferentes debería producir dos commits separados. Los commitspequeños facilitan a otros desarrolladores a) comprender los cambios b) revertirlos si algo salió mal.

Hacer commits temprano y con frecuencia

Hacer commits temprano y a menudo, mantiene sus commits atómicos y lo ayuda a realizar solo los cambios relacionados. Además, le permite compartir su código con más frecuencia con otros y evitar conflictos de fusión (merge).

Pruebe su código antes de hacer commit

Resista la tentación de hacer commit a algo que “cree” que se ha completado. Pruébelo a fondo para asegurarse de que realmente esté completo y no tenga efectos.

Acuerde un flujo de trabajo

Git te permite elegir entre muchos flujos de trabajo diferentes: ramas de larga duración (long-running branches), ramas de características (feature branches), fusiones (merge) o rebase, git-flow, etc. El que elijas depende de un par de factores: tu proyecto, tus flujos de trabajo generales de desarrollo e implementación, etc. Sin importar cual elijas para trabajar, solo asegúrese de acordar un flujo de trabajo común que todos sigan.

Otras convenciones para explorar o mejorar esta

Fuentes

Writing Better Commit Messages por Apurva Jain

Versionado Semántico por Tom Preston-Werner

Foto por Roman Synkevych en Unsplash

Author: Alexander Andrade

Ingeniero de Sistemas, MBA y Especialista en Gerencia de Proyectos Tel: +57-317-241-5118
Salir de la versión móvil