Cómo escribir mensajes de compromiso que los responsables de proyectos apreciarán

¿Conoces el dicho Si sigues mirando al pasado, te pierdes el futuro? Bueno, en el contexto de la programación y el trabajo con Git, eso no es cierto. Tu historial de commits juega un papel importante en el futuro de los proyectos de código abierto a los que contribuyes, y.

Sabes el dicho “Si te quedas mirando al pasado, te perderás el futuro”? Bueno, en el contexto de la programación y el trabajo con Git, eso no es cierto.

Tu historial de commits juega un papel importante en el futuro de los proyectos de código abierto a los que contribuyes, y los mensajes de commit son clave para hacer esto posible.

¿Qué son los mensajes de commit, preguntas? Estas breves explicaciones describen los cambios que hiciste en el código y son muy útiles si ocurren cosas como errores.

Los mensajes de commit también son buenos puntos de control si estás volviendo a un proyecto de código abierto en el que no has contribuido por un tiempo y necesitas recordar los cambios que has hecho hasta ahora.

¿Te sientes intimidado? No te preocupes. En esta guía rápida, aprenderás cómo escribir mensajes de commit efectivos.

¿Qué hace que un mensaje de commit sea malo?

Como la mayoría de las cosas en la vida, tenemos que aprender sobre lo que hace que un mensaje de commit no sea útil antes de aprender a escribir uno bueno.

Veamos un ejemplo:

mencionar información

Aunque este mensaje de commit describe el cambio, no explica por qué se realizó el cambio, lo que puede dejar a los mantenedores confundidos.

Tampoco indica qué tipo de información se mencionó. Los mantenedores podrían estar preguntándose “¿Era un fragmento de código que faltaba? ¿Un enlace a una sección específica?”. Estas son cosas que debes evitar al escribir mensajes de commit.

Ahora que hemos visto lo malo, aprendamos cómo convertir este mensaje de commit en algo que los mantenedores puedan entender.

Características de un buen mensaje de commit

Recuerdas cómo dije que el mensaje de commit anterior era un poco vago? Bueno, así es cómo podemos solucionarlo:

Paso 1: Menciona el tipo

Aquí es donde especificas el tipo de cambio que estás realizando en el código. Esto facilita a los mantenedores y otros colaboradores comprender mejor tu contribución.

Así es cómo se vería este paso con el commit de ejemplo:

feat: mencionar información

Dado que el commit de ejemplo parece centrarse en agregar algún texto, decidí usar feat porque a menudo se utiliza para describir contribuciones donde se agrega información o una nueva función a un proyecto de código abierto.

Aquí hay algunas otras abreviaturas comunes que se utilizan para categorizar los commits:

docs: Esto se usa comúnmente para describir revisiones de versiones actuales o actualizaciones de la documentación de un proyecto de código abierto.
fix: Esto se usa típicamente para solucionar errores en el código del proyecto o pequeños errores gramaticales en la documentación del proyecto.
chore: Esto se usa a menudo para una contribución que puede llevar más tiempo de lo habitual para completarse.

Paso 2: Resumen del cambio

Aquí das una descripción general del cambio y cómo lo hiciste. Esto ayuda a los mantenedores a comprender cómo tu contribución resuelve el problema que estás intentando solucionar.

Es importante tener en cuenta que GitHub tiene un límite de 72 caracteres, por lo que debes mantener tu descripción dentro de ese rango. Volvamos a nuestro ejemplo:

feat: mencionar información

Recuerdas cómo dije que no especifica la corrección que se realizó? Bueno, después de pensar un poco, decidí escribir esto:

feat: mencionar a Christine Peterson en la introducción del curso

¡Eso es mucho mejor! 🙂 A diferencia de antes, esta versión del commit de ejemplo menciona el tipo de información y especifica dónde se agregó en el proyecto. Esto ayuda a los mantenedores a comprender mejor por qué se realizó esta contribución.

Paso opcional: Agrega una descripción

Aquí describes el cambio con más detalle mencionando por qué lo hiciste. Aunque este paso es opcional, considera hacerlo para que los mantenedores puedan tener una idea de cómo tu contribución mejora o resuelve un problema en su proyecto.

Así es cómo se vería con nuestro ejemplo:

Decidí agregar esta información para que los participantes obtengan información precisa.

Cuando hice la descripción, decidí mantenerla breve pero específica. De esa manera, ayudaría a los mantenedores a comprender por qué hice esta contribución y cómo mejora el proyecto.

Ahora unamos todas estas partes:

feat: mencionando a Christine Peterson en la introducción del curso. Decidí agregar esta información para que los participantes puedan obtener información precisa

Ahora, en comparación con el ejemplo original, este mensaje de commit es más efectivo porque hace lo siguiente:

Especifica el tipo de commit que se realiza
Describe cómo la contribución mejora el proyecto
Resume el cambio realizado

¡Se ve genial, ¿verdad? 😉

Conclusión

Tanto si eres un nuevo colaborador como un veterano experimentado, escribir mensajes de commit de manera efectiva es crucial para comunicar tus contribuciones a los mantenedores del proyecto.

Si estás buscando formas de mejorar tus habilidades de escritura de mensajes de commit, echa un vistazo a Conventional Commits. Además, sígueme en BioDrop para ver mis redes sociales y otros artículos técnicos.