Hoy en día, al escribir una aplicación, ya sea solo o en equipo, lo más normal es que subamos nuestro código a un repositorio (publico o privado).
Como puedes ver, ambos comentarios tienen una estructura muy parecida, que consta de los siguientes elementos:
- Título. El cual es una descripción breve, se recomiendan menos de 50 caracteres, y proporcione un contexto de qué es lo que se incluye en el commit.
- Cuerpo. Aquí, se explica el por qué o para qué del cambio, NO el cómo. Este es un error muy frecuente, explicamos todos los cambios que hicimos en el código pero nunca decimos para qué hicimos esos cambios. También, se debe indicar si este cambio genera algunos efectos secundarios o alguna otra consecuencia que no sea obvia.
Si necesitas explicar una serie de cosas o listar algunos elementos, se recomienda usar guiones medios o asteriscos. - Pie. Información adicional o meta información. Si estás usando algún sistema de seguimiento de tareas como Jira, este es el lugar para indicar el número de los elementos de trabajo o tickets que se afectan o cierran con este commit.
- Separar el título del cuerpo del mensaje usando una línea en blanco.
- Limitar el título a 50 caracteres.
- Colocar la primera línea del título en mayúscula.
- No terminar el título con punto.
- Escribir el título usando el tiempo imperativo.
- Escribe el cuerpo usando líneas de 72 caracteres.
- Usa el cuerpo para explicar el qué y por qué y no el cómo.
Si el título es suficiente para entender los cambios en el commit, el cuerpo se puede excluir.
Estos son algunos ejemplos de mensajes de commit que siguen estas recomendaciones:
Simplifica el proceso de validación de información del usuario
Elimina la información innecesaria para crear la cuenta del usuario.
Con este cambio, la información obligatoria se limita a:
- Nombre
- Correo electrónico
- Avatar o Foto
Si se requiere información adicional esta se solicita en el momento
que se use, si es que no existe previamente. A los usuarios que
completen toda la información (obligatoria y opcional), se les
premia con 10 puntos de recompensa.
Resuelve: #1234
Impacta en: #567 y #890
Claro, las anteriores son solo recomendaciones que deben ser ajustadas dependiendo de las necesidades particulares del equipo de trabajo y no deben ser tomadas como reglas o limitantes. Por ejemplo, el problema más típico que me he topado es con las recomendaciones del número de caracteres. En general, el español es un idioma en el que las palabras son más largas que en inglés y donde no usamos tantas abreviaturas, así que si 50 no es suficiente, no temas aumentar este límite a, por ejemplo, 60 0 65.
Un ejemplo de esto último:
Add validations in the mandatory user account fields -> 53 caracteres.
Agrega validaciones en los campos obligatorios de la cuenta del usuario -> 72 caracteres
Chris explica el por qué de estas reglas dentro de su artículo.
Además de esto, en algunos repositorios, como el de Angular, los lineamientos indican dividir el título en dos partes:
1. El tipo de cambio en el commit. Usar un prefijo para indicar si estamos agregando, eliminando, refactorizando, etc.
2. El alcance del cambio. Animaciones, documentos, formularios, etc.
Esto es algo que se conoce como commits o títulos semánticos
Así, el mensaje título del mensaje anterior podrá quedar:
Agrega (formulario): validaciones en los campos obligatorios de la cuenta del usuario
Si en tu equipo de trabajo deciden que el tipo debe escribirse, por ejemplo, en inglés y mayúsculas, el título puede quedar así:
ADD (form): validaciones en los campos obligatorios de la cuenta del usuario
En algunos repositorios incluso agregan algunos emoji para hacer aún más rápida la identificación del tipo de cambio:
➕ ADD (form): valida los campos obligatorios de la cuenta del usuario
⚙ CONF: mueve la configuración de archivos a base de datos
📕DOC (cart): actualiza la documentación del servicio de carro de compra
En otros repositorios, la convención es colocar en la primera parte del título el número del ticket o elemento de trabajo, y despúes una descripción:
#879: Agrega validaciones en el los campos obligatorios de la cuenta del usuario
Nuevamente, esto puedes ajustarlo de acuerdo con las convenciones definidas por tu equipo de trabajo.
Para terminar, y esto ya no está relacionado directamente con estas sugerencias. Si aún estás aprendiendo o quieres mejorar tus habilidades en Git, recuerda que el libro Pro Git es la fuente oficial y actualizada sobre el uso de Git (además de que es público y gratuito).
Espero que estas sugerencias te sean útiles y ayuden a escribir cada día mejores mensajes para tus commits, y en general para la información de los cambios en tu proyecto.
¿Tienes alguna otra recomendación que te haya funcionado y quieras compartir? Puedes hacerlo aquí o colocarlo en mis redes sociales para compartirlo con la comunidad.
Espero que este tutorial les sea de utilidad. Si tienen alguna duda,
sugerencia, comentario o aclaración, pueden dejarla en la sección de
comentarios o enviar un correo a programadorjavablog@gmail.com (pueden agregarme al chat de gmail). También pueden seguir JavaTutoriales en las siguientes redes sociales:
Saludos y gracias.