Plantilla para mensajes de confirmación en Git

Todos hemos vivido el XKCD sobre los mensajes de confirmación en git en algún momento.

Yo no soy una excepción. Así es como se ven los mensajes de confirmación para mi blog:

Como el historial de git de mi blog solo lo veo yo, está bien. He aceptado que nunca podré aprovechar al máximo git en mi blog, y estoy totalmente bien con eso.

Desafortunadamente, algunas personas tratan los proyectos reales con múltiples contribuyentes de la misma manera que trato mi blog. He encontrado que esta práctica es el resultado de la ignorancia más que de la pereza. Así que voy a compartir algunos consejos sobre cómo deberías usar los mensajes de confirmación en proyectos reales.

¿Por qué deberías preocuparte?

😤 No me importa, ¡sáltate a la plantilla! 🚀

Git es una herramienta poderosa, incluso si solo la usas para mantener un historial de cambios de código y no aprovechas sus características más potentes.

Sin embargo, encontrarás que cuanto más profundizas, más poderoso se vuelve git. También encontrarás que muchas de las características más útiles de git funcionan bajo el supuesto de que los mensajes de confirmación son útiles.

Piensa en la última vez que usaste git blame. ¿Habría sido útil si encontraste un mensaje de confirmación que decía, corrigió un error grave? Probablemente no, probablemente estabas tratando de encontrar más contexto sobre el código en el que estabas trabajando; necesitabas una explicación de qué y por qué.

Los mensajes de confirmación de Git deben incluir el qué y el por qué detrás de cada cambio para que los valientes exploradores de git del mañana puedan ponerse en la mente del autor de una confirmación. Si un mensaje de confirmación no incluye esa información, ¿por qué escribir uno en absoluto? Los mensajes de confirmación solo son útiles si son útiles para alguien que intenta entender un cambio en algún momento en el futuro.

Para crear una plantilla para un buen mensaje de confirmación, dividiré los mensajes de confirmación en varias secciones.

Primero, la línea de asunto

En un mensaje de confirmación, la primera línea (a veces llamada línea de asunto) debe estar aislada del cuerpo. Idealmente, esta línea resume los cambios realizados en una confirmación.

Cuando escribo líneas de asunto, trato de terminar la frase, "Esta confirmación..."

Por ejemplo, podría escribir una línea de asunto que diga algo como, Eliminar código comentado y no utilizado. Eso terminaría mi frase de manera agradable: "Esta confirmación eliminará el código comentado y no utilizado".

Cuando se trata de formatear tu línea de asunto, hay una o dos reglas para recordar.

Primero, el primer carácter de tu línea de asunto debe estar en mayúscula; esto es solo una convención común. En mi experiencia, también hace que sea más fácil leer listas largas de confirmaciones de una línea.

Segundo, tu mensaje de confirmación no debe tener más de cincuenta caracteres. Esto se debe a que herramientas como GitHub truncan la línea a los cincuenta caracteres. Por lo tanto, para permitir que otros escaneen y comprendan efectivamente tu línea de asunto, debes intentar resumir todo el cambio en cincuenta caracteres.

La primera línea de mi plantilla de mensaje de confirmación se ve así:

Resumir el cambio en menos de 50 caracteres

A continuación, el primer "párrafo" del cuerpo

En algunas confirmaciones, la línea de asunto es suficiente para transmitir toda la idea. Por ejemplo, si tu confirmación será Añadir una coma al README, probablemente no tengas que explicarte.

Sin embargo, en la mayoría de las confirmaciones, tus cambios podrían beneficiarse de un contexto adicional. No queremos que los desarrolladores futuros pierdan el contexto mientras intentan entender el razonamiento detrás de un cambio.

Aquí es donde entra en juego el cuerpo del mensaje. Divido el cuerpo en "párrafos", que son solo cadenas de texto vagamente definidas separadas por espacios en blanco. Pueden ser viñetas, oraciones u otra cosa; lo importante es que sean fáciles de leer y entender desde el principio.

En el pasado, solía usar el primer párrafo del cuerpo del mensaje de confirmación para explicar lo que había hecho. Estos días, me he alejado de qué y he comenzado a documentar por qué.

La mayoría de los mensajes de confirmación son casi inútiles porque se centran en QUÉ se hizo en lugar de POR QUÉ. Esto es exactamente lo incorrecto en lo que centrarse. Siempre puedes reconstruir qué cambios contiene una confirmación, pero es casi imposible descubrir la razón por la que se hizo.

Entonces, en este caso, queremos comenzar con por qué estamos haciendo el cambio.

Aquí hay un ejemplo:

Lo genial de estos "párrafos" es que solo hay una regla de formato: dividir en 72 caracteres. Esto es más una tradición heredada que algo sustancial. Sin embargo, la razón principal es que esto permite a git un espacio para indentar (asumiendo un límite máximo de caracteres de 80). Recomiendo seguir esta regla aunque no siempre sea estrictamente necesaria.

Aquí está la plantilla de mensaje de confirmación hasta ahora:

Ahora el segundo "párrafo" del cuerpo

Ahora que hemos resumido el cambio y compartido nuestras razones para hacerlo, podría ser prudente explicar exactamente lo que hicimos en una forma más detallada.

Uso el segundo "párrafo" para dar una explicación más detallada de lo que hice en el cambio, por ejemplo:

Esta sección del cuerpo del mensaje debe explicar lo que se hizo con un poco más de profundidad que el resumen de 50 caracteres. El formato depende de ti (siempre que estés dividiendo en 72 caracteres).

Aquí está la plantilla actualizada:

Las otras secciones: Notas adicionales y co-autores

En este punto, estamos escribiendo mensajes de confirmación efectivos y coherentes. Sin embargo, a veces un mensaje de confirmación necesita algunas notas adicionales. Eso se puede hacer en la última sección.

Por ejemplo:

En este ejemplo, pude:

En este punto, cualquiera que vea este mensaje de confirmación sabrá:

Esto hace que nuestro mensaje de confirmación sea infinitamente más útil para nuestros futuros yoes y cualquier otro desarrollador que necesite entender nuestro código.

Incluso si no estás de acuerdo con mi metodología para escribir mensajes de confirmación, es difícil negar que debemos escribir mensajes de confirmación que permitan a otros desarrolladores ponerse en nuestra mente cuando están leyendo nuestro código.

Creo que la mayoría de las personas están de acuerdo en que una característica distintiva del "buen" código es la mantenibilidad; puedes aumentar la mantenibilidad de tu código escribiendo mensajes de confirmación que ayuden a otros a entender e incluso cambiar tu código en el futuro.

La plantilla final