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
- Fomente la transparencia comunicando la naturaleza de los cambios en su código base a una variedad de audiencias: compañeros de equipo existentes, futuros colaboradores y, a veces, el público y otras partes interesadas.
- Peer Code Review (revisión de código por pares) requiere una convención de mensajes de commits de Git bien formateados para comunicar el contexto sobre los cambios a los compañeros desarrolladores.
- Se requiere un historial de commits estructurado para comprender qué cambios notables se han realizado entre cada lanzamiento (o versión) del proyecto.
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 blame, git revert, git rebase, git 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 versión MAYOR (MAJOR) cuando realizas un cambio incompatible en el API,
- La versión MENOR (MINOR) cuando añades funcionalidad que compatible con versiones anteriores, y
- La versión PARCHE (PATCH) cuando reparas errores compatibles con versiones anteriores.
- Hay disponibles etiquetas para prelanzamiento (pre-release) y metadata de compilación como extensiones al formato MAYOR.MENOR.PARCHE.
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.
- Generando automáticamente el CHANGELOG (historial de cambios).
- Determinando automáticamente los cambios de la versión semántica (según los tipos de commits recibidos).
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 y 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
- feat: (feature o característica) la nueva característica que se agrega a una aplicación en particular.
- fix: (corrección) una corrección de errores (esto se correlaciona con los PARCHES (PATCH) en SemVer).
- style: (estilo) característica y actualizaciones relacionadas con el estilo.
- refactor: (refactorización) refactorizar una sección específica del código base.
- test: (prueba) todo lo relacionado con las pruebas.
- docs: (documentación) todo lo relacionado con la documentación.
- chore: (tarea) mantenimiento regular del código
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.
- Limite la línea de asunto a 50 caracteres
- Su mensaje de commit no debe contener espacios en blanco ni signos de puntuación.
- No termine la línea de asunto con un punto
- Use el tiempo presente o imperativo (recuerda: siempre en inglés) en la línea de asunto.
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.
- Separe el asunto del cuerpo con una línea en blanco.
- Limite cada línea a 72 caracteres.
- No asuma que el revisor entiende cuál fue el problema original, asegúrese de agregarlo.
- No creas que tu código se explica por sí mismo.
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 #658, reopen #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:
- Un commit del tipo fix corrige un error en su código base (esto se correlaciona con la versión PARCHE de SemVer).
- Un commit del tipo feat introduce una nueva característica en el código base (esto se correlaciona con la versión MENOR de SemVer).
- CAMBIO IMPORTANTE: un commit que tiene un pie de página (footer) BREAKING CHANGE o agrega un ! después del type / scope, introduce un cambio de software importante (que se correlaciona con la versión MAYOR de SemVer). Un BREAKING CHANGE puede formar parte de commits de cualquier tipo.
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 commits, sino 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
- 🇪🇸 Commits Convencionales: Especificación para dar significado a los mensajes de los commits haciéndolos legibles para máquinas y humanos.
- 🇺🇸 Gitmoji: An emoji guide for your commit messages: colocar unos emojis al comienzo del mensaje del commit para hacer más rápida la comprensión del motivo del mismo.
- 🇺🇸 What Makes a Good Pull Request, Anyway? Know the tools and components to create pull requests like a pro.
Fuentes
Writing Better Commit Messages por Apurva Jain
Versionado Semántico por Tom Preston-Werner
Foto por Roman Synkevych en Unsplash