Cómo escribir un GRAN mensaje de Git Commit

Introducción

Elaborar mensajes de confirmación de Git eficaces puede mejorar significativamente la colaboración, la legibilidad del código y el mantenimiento del proyecto durante años. Sin embargo, a menudo se pasa por alto o se trata como algo secundario en el proceso de desarrollo. En esta entrada del blog, iré directo al grano y resumiré los principios clave para escribir mensajes de confirmación de Git sobresalientes que todo desarrollador debería seguir.

1. Empiece con un verbo imperativo en mayúsculas para el asunto del mensaje

Un mensaje de confirmación debe indicar claramente lo que hace esta confirmación. Utilice un verbo imperativo en mayúsculas al principio para facilitar la lectura y el mantenimiento.

Ejemplo

• Añadir nueva función para el inicio de sesión de los usuarios

• Corregir error en el procesamiento de pagos

• Actualizar la documentación de los puntos finales de la API

2. La línea de asunto debe ser concisa

El mensaje de confirmación debe ser lo suficientemente descriptivo como para transmitir el propósito de la confirmación, pero lo suficientemente conciso como para ser escaneado rápidamente. Intenta que el asunto tenga unos 50 caracteres y utiliza el cuerpo del mensaje para dar más detalles.

• Buen mensaje de confirmación: Refactorizar el módulo de autenticación de usuarios

• Mensaje de confirmación erróneo: Refactorizado el módulo de autenticación de usuario para mejorar el rendimiento y la legibilidad

3. Separe el resumen del cuerpo con una línea en blanco

Si tu mensaje de confirmación necesita más detalles, añade un cuerpo. Asegúrate de añadir una línea en blanco entre el resumen y el cuerpo para hacerlo más legible.

Añadir caché local para mejorar el rendimiento de las aplicaciones

Este cambio implementa un mecanismo de caché local para reducir la carga de la base de datos
y mejorar los tiempos de respuesta globales en la red. La caché se invalida cada diez minutos para garantizar la frescura de los datos.

4. Utilizar el modo imperativo

Teniendo en cuenta la convención estándar, escriba los mensajes de confirmación en modo imperativo, un tiempo asociado normalmente a órdenes y acciones. Esto es una instrucción sobre lo que se está haciendo cuando se aplica la confirmación.

Ejemplos:

• Corregir: Añadir autenticación de usuario

• Incorrecto: Añadido autenticación de usuario

• Corregir: Fijar autenticación de usuario

• Incorrecto: Corregido autenticación de usuario

• Corregir: Actualizar autenticación de usuario

• Incorrecto: Actualizado autenticación de usuario

5. Explicar el "qué" y el "por qué" en el cuerpo

Utiliza el cuerpo para dar más detalles sobre el cambio: explica qué se ha hecho y por qué. Esto facilita a los demás -y a ti mismo en el futuro- la comprensión del contexto y la razón del cambio:

• Qué: Refactorización de la lógica de autenticación

• Por qué: Mejorar el rendimiento y reducir la duplicación de código

Por ejemplo:

Refactorización de la lógica de autenticación

Se ha extraído la lógica de autenticación de una clase a un módulo independiente para mejorar el rendimiento y reducir la duplicación de código. Este cambio
también facilitará la implementación de futuras mejoras.

6. Utilice viñetas para las listas

Si la confirmación incluye varios cambios, escríbalos en viñetas. Esto facilita la lectura y comprensión de cada cambio:

Mejorar la gestión de errores en el procesamiento de pagos

- Validación de los campos de pago
- Gestión de errores de API con mecanismo de reintento
- Registro de mensajes de error detallados para depuración

7. Referencia a asuntos o entradas relevantes

Si tu confirmación resuelve o está relacionada con una incidencia o tarea específica, haz referencia a ella en tu sistema de gestión de proyectos, por ejemplo, GitHub Issues o Jira. Esto ayuda a mantener actualizado el estado de las incidencias, y el contexto será muy útil para los lectores más adelante.

Corrección del cálculo incorrecto del total (#4342)

Corregida la lógica de cálculo de los totales de los pedidos, asegurando que
que se apliquen los impuestos y descuentos.

8. Revisar y corregir

Antes de enviarlo al repositorio, tómese un momento para revisar su mensaje. Comprueba si hay errores ortográficos, gramaticales o de claridad. Un mensaje de confirmación bien escrito refleja profesionalidad y atención al detalle, lo que puede ahorrar tiempo y dolores de cabeza.

Lista de comprobación rápida

• Mayúsculas: ¿Comienzas el asunto con mayúscula?

• Conciso: ¿Su línea de asunto tiene 50 caracteres o menos?

• Línea en blanco: ¿Has añadido una línea en blanco después del resumen si hay cuerpo?

• Modo imperativo: ¿Está el mensaje en modo imperativo?

• Detalle: ¿Explica el cuerpo (si está presente) el qué, el por qué y el cómo?

• Listas: ¿Has utilizado viñetas para tu lista?

• Referencias: ¿Ha hecho referencia a algún tema o RP relevante?

• Corrige: ¿Has comprobado la claridad y las erratas?

Conclusión

Escribir buenos mensajes de confirmación de Git mejora la colaboración y el mantenimiento del proyecto. Siguiendo estas sencillas pautas -utilizando verbos imperativos, manteniendo el asunto conciso, explicando el "qué" y el "por qué", y haciendo referencia a los temas relevantes- crearás un valioso historial del proyecto fácil de navegar y comprender. También tenemos otro post titulado "3 razones por las que deberías usar commits convencionales" si quieres saber más.

También nos encantaría que te unieras a nosotros en el Slack de la comunidad de Vonage o envíanos un mensaje en X y nos pondremos en contacto contigo. Gracias nuevamente por leer, ¡y te alcanzaré en la próxima!

¡Feliz compromiso!