Para crear un historial de revisión útil, los equipos primero deberían ponerse de acuerdo en una convención para los mensajes de commit (mensajes de confirmación). Eso también aplica para proyectos personales.
Recientemente pregunté en Hashnode, "¿Cuál convención de mensaje usas en tus commits en el trabajo?" recibí muchas respuestas de usuarios quejándose de las convenciones que usan en el trabajo y proyectos personales.
En este artículo explicaré cómo escribir un buen mensaje de commit y por qué tú deberías darle importancia.
PS: Este artículo fue publicado primero aquí.
Introducción al control de versiones con Git
El software de control de versiones es una parte esencial de las prácticas de desarrollo de software modernas.
Por mucho, Git es el controlador de versiones más ampliamente utilizado en el mundo. Es un proyecto de código abierto, distribuido y activamente en desarrollo. Fue originalmente desarrollado en 2005 por Linus Torvalds, el famoso creador del kernel Linux.
¿Qué es un commit?
El comando commit se usa para confirmar los cambios en el área de preparación y guardarlos en el repositorio local en Git. Sin embargo, antes de guardar algún cambio, tienes que decirle a Git cuáles cambios quieres incluir de los muchísimos que puedes haber hecho. Una excelente manera de hacerlo es agregar un mensaje en el commit para identificar tus cambios.
Opciones de comando commit
- -m
Esta opción establece el mensaje del commit.
git add static/admin/config.yml
git commit -m "Configurar múltiples roles para netlify-cms git gateway"
- -a ó --all
Esta opción confirma todos los archivos en el área de trabajo (esos nuevos, con modificaciones, o incluso eliminados) automáticamente..
git commit -a -m "Agregar un nuevo rol para netlify-cms git gateway"
- --amend
Esta opción reescribe el último commit con cualquier cambio que esté en el área de preparación o un nuevo mensaje, y solo debería ser incluido en commits que no han sido aún sincronizados con el repositorio remoto.
git add .
git commit --amend -m "Actualizar roles para netlify-cms git gateway"
¿Por qué debería escribir un buen mensaje de commit?
Puede que digas: "Es solo un proyecto personal". Sí, puede que estés trabajando solo ahora, pero, ¿Qué pasa cuando trabajas con un equipo o contribuyes al código abierto?
Un mensaje de commit bien elaborado es la mejor manera de comunicar el contexto del cambio realizado a otros desarrolladores trabajando en el proyecto y también al futuro tú.
¿Haz alguna vez intentando ejecutar el comando git log en uno de tus proyectos viejos para ver los mensajes de commit "raros" que has usado desde su creación? Quizá sea difícil entender por qué hiciste algunos cambios en el pasado y es probable que desees haber leído este artículo antes.
Los mensajes de commit pueden comunicar adecuadamente el porqué un cambio fue hecho y de este modo entenderlo fácilmente. Haciendo más eficiente la colaboración y el desarrollo.
Cómo escribir mensajes de commit con Git
Hasta hoy, solamente usaba git commit -m "Arregle X para permitir que Y use Z" en mis proyectos personales especificando solo un título sin ninguna descripción extra. Esto es perfecto para parches pequeños y claros de código como, git commit -m "Corregi error tipográfico en README.md" pero en casos donde hay cambios más extensos necesitamos agregar más detalles.
Método editor
Ejecuta git commit sin un mensaje u opción y se abrirá tu editor de texto predeterminado para escribir el mensaje de commit.
Para configurar tu editor "predeterminado":
git config --global core.editor nano
Esto configurará Git para usar nano como editor predeterminado. Reemplaza "nano" con "emacs", "vim" o cualquiera de tu preferencia.
En el editor que se abrió, usa la primera línea para el título (corta descripción), deja una línea en blanco y todo lo de más es para la descripción extendida (cuerpo del mensaje).
<Resumir los cambio(s) en alrededor de 50 caracteres o menos>
<Descripción explicativa más detallada del cambio envuelto en aproximadamente 72 caracteres>
Método de línea de comando
git commit -m "Sujeto" -m "Descripción..."
El primer argumento -m es para el título (corta descripción), y el siguiente es para la descripción extendida (cuerpo del mensaje).
Cómo escribir buenos mensajes de commit
Existen muchas convenciones que son usadas por diferentes equipos y desarrolladores para escribir bien mensajes de commit. Aquí solo mostraré algunas reglas generales y consejos para escribir buenos mensajes de commit – puedes escoger cuál de estas reglas quieres seguir. Y si trabajas para una compañía o contribuyes al código abierto, tienes que aceptar y adaptarte a su convención.
Por consistencia, puedes usar una convención para el trabajo y otra para proyectos personales. Cuando cambies de trabajo, puede que la convención sea diferente en el nuevo lugar.
Esta es una gran plantilla de un buen mensaje de commit escrito originalmente por Tim Pope:
Aprovechar, Resumen breve (50 caracteres o menos)
Texto explicativo más detallado, si es necesario. Envuélvalo a unos 72 personajes más o menos. En algunos contextos, la primera línea se trata como asunto de un correo electrónico y el resto del texto como cuerpo. El espacio en blanco línea que separa el resumen del cuerpo es fundamental (a menos que omita todo el cuerpo); herramientas como rebase pueden confundirse si ejecuta el dos juntos.
Escriba su mensaje de confirmación en imperativo: "Corregir error" y no "Corregido error" o "Corrige error". Esta convención coincide con los mensajes de confirmación generados mediante comandos como git merge y git revert.
Los párrafos adicionales vienen después de las líneas en blanco.
- Las viñetas también están bien
- Normalmente se utiliza un guión o asterisco para la viñeta, seguido de un espacio único, con líneas en blanco en el medio, pero las convenciones varían aquí
- Usar una sangría colgante
Si utiliza un rastreador de problemas, agregue una referencia a ellos en la parte inferior, como tal:
Soluciona: #123
¿Se ve bien, no? Así es cómo tú puedes hacer el tuyo genial también:
- Especifica el tipo de commit:
feat: La nueva característica que agregas a una aplicación en particular
fix: Un parche para un error
style: Características o actualizaciones relacionadas con estilos
refactor: Refactorizar una sección específica de la base de código
test: Todo lo relacionado con pruebas
docs: Todo lo relacionado con documentación
chore: Mantenimiento de código regular. - Separa el título del cuerpo del mensaje con una línea en blanco.
- Tu mensaje de commit no debería contener ningún mensaje de espacios en blanco.
- Quita signos de puntuación innecesarios.
- No termines el título con un punto.
- Usa mayúsculas al inicio del título y por cada párrafo del cuerpo del mensaje.
- Usa el modo imperativo en el título.
- Usa el cuerpo del mensaje para explicar cuáles cambios has hecho y por qué los hiciste.
- No asumas que las personas que revisará el código entiende cuál era el problema original, asegúrate de agregar la información necesaria.
- No piense que tu código se explica solo.
- Sigue la convención del mensaje de commit definida por tu equipo.
Conclusión
La parte más importante de un mensaje de commit es que sea claro y entendible. A final de cuentas, escribir buenos mensajes de commit demuestra que tan buen colaborador eres. Los beneficios de escribir un buen mensaje de commit no se limitan a tu equipo, de hecho, se expanden a ti y tus futuros colaboradores.
Traducido del artículo de Bolaji Ayodeji - How to Write Good Commit Messages: A Practical Git Guide