Cómo escribir un mensaje Git Commit eficaz y útil

Los mensajes de confirmación son descripciones breves de cada confirmación en un sistema de control de versiones como Git. Cuando realiza cambios en los archivos de su proyecto, debe proporcionar un mensaje que explique qué hacen o por qué los hizo.

Los mensajes de confirmación sirven como una forma de documentación y comunicación. Desempeñan un papel crucial en el mantenimiento de un historial de versiones claro y organizado de un proyecto. Aprenda a escribir buenos mensajes de confirmación y los demás miembros de su equipo apreciarán aún más su trabajo.

Estructura de un buen mensaje de compromiso

Un buen ejemplo de un mensaje de confirmación incluye cuatro secciones: Tipo, Descripción, Cuerpo y Pie de página.

Al igual que:

: 
[cuerpo opcional]
[pie de página opcional]

Tipo

El tipo describe el tipo de cambio realizado en la confirmación actual. Puede usar cualquier sistema que tenga sentido para sus circunstancias. Por ejemplo, aquí hay algunas palabras clave de muestra que puede usar para señalar cada tipo de cambio, junto con el uso de ejemplo:

• logro: sus cambios introducen una nueva función.
• arreglar: arreglas un error.
• refactorizar: su código de refactores de cambio sin corregir un error o agregar una nueva función.
• prueba: realiza cualquier cambio relacionado con las pruebas. Por ejemplo, cuando usted escribir pruebas con Jest o cualquier otro marco de prueba tu eliges.
• faena: cambios no relacionados con una corrección, función o prueba. Por ejemplo, actualizar dependencias.
• documentos: cuando actualice la documentación.
• estilo: cambios que no afectan el significado del código, como agregar espacios en blanco, puntos y comas faltantes, etc.
• rendimiento: cambios relacionados con mejoras de rendimiento.
• construir: cuando realiza cambios que afectan los archivos de compilación.
• ci: cambios relacionados con la integración continua.
• revertir: al volver a una confirmación anterior.

Descripción

La "descripción" de un mensaje de confirmación es un resumen conciso y descriptivo de los cambios realizados en la confirmación. Sirve como un titular que captura la esencia de la confirmación.

Al escribir la descripción, tenga en cuenta lo siguiente:

• Hágalo lo suficientemente claro y específico para describir la confirmación de un vistazo.
• Hazlo breve y conciso. Idealmente, lo mejor sería limitarlo a 50 caracteres o menos.
• Escríbalo en tiempo presente, incluso si está describiendo cambios ya realizados.
• Haz uso del estado de ánimo imperativo mientras lo escribes.
• Comience con una letra mayúscula.
• No lo termines con un punto.

Por ejemplo:

hazaña: Implementar el cambio de modo oscuro para la página de inicio

Este ejemplo muestra cómo puede escribir la descripción de una confirmación que implementa el modo oscuro. utiliza el logro escriba porque introduce una nueva característica.

Cuerpo (Opcional)

La sección del cuerpo de un mensaje de confirmación proporciona detalles adicionales y contexto sobre los cambios realizados en la confirmación. No siempre necesitará un cuerpo, pero puede ayudar a proporcionar más información, explicar el razonamiento de un cambio o describir cualquier consideración técnica.

Aquí hay algunas cosas a tener en cuenta al escribir la sección del cuerpo de un mensaje de confirmación:

• Git nunca envuelve el texto automáticamente, así que envuélvelo manualmente en 72 caracteres cuando escribas el cuerpo. Esto le da a Git suficiente espacio para sangrar el texto, haciéndolo más legible.
• Use el cuerpo para explicar qué sucedió en el cambio, por qué hizo el cambio y el razonamiento detrás de su cambio.
• Debe dejar una línea en blanco entre la línea de descripción y el cuerpo. Esto le permite a Git distinguir entre ellos.
• Si la confirmación introduce múltiples cambios o afecta diferentes áreas del código base, considere usar viñetas o párrafos para desglosar las modificaciones. Esto mejora la legibilidad y ayuda a los lectores a comprender los diferentes aspectos de la confirmación.

Por ejemplo:

hazaña: agregar GitHub como proveedor de OAuth
Integre GitHub como un proveedor de OAuth para habilitar sin problemas 
autenticación con cuentas de GitHub.
- Implementar el flujo de autenticación de OAuth con la API de GitHub
- Configure los puntos finales y la configuración necesarios para la autenticación de GitHub
- Actualice la interfaz de usuario para incluir la opción de inicio de sesión de GitHub

El ejemplo anterior muestra un buen mensaje de confirmación de Git para una función que agrega GitHub como proveedor de OAuth a su aplicación. Este mensaje de confirmación tiene una línea de resumen concisa (50 caracteres o menos), un texto explicativo más detallado (ajustado a unos 72 caracteres) y viñetas para obtener información adicional.

La sección de pie de página en un mensaje de confirmación es una parte opcional que proporciona información adicional o metadatos relacionados con la confirmación. Por lo general, se coloca después de la sección del cuerpo, separado por una línea en blanco. El pie de página puede incluir varios tipos de información, como referencias a problemas relacionados, etiquetas o notas especiales.

Al hacer referencia a problemas, solicitudes de extracción u otros elementos relacionados, use la sintaxis o el formato adecuados requeridos por el sistema de seguimiento de problemas de su proyecto. Esto garantiza que las referencias se reconozcan y vinculen correctamente.

Por ejemplo:

hazaña: Agregar GitHub como proveedor de OAuth
Integre GitHub como un proveedor de OAuth para habilitar sin problemas 
autenticación con cuentas de GitHub.
- Implementar el flujo de autenticación de OAuth con la API de GitHub
- Configure los puntos finales y la configuración necesarios para la autenticación de GitHub
- Actualice la interfaz de usuario para incluir la opción de inicio de sesión de GitHub
Resuelve: #123
Ver también: #456, #789

El pie de página hace referencia al problema relacionado n.º 123 y menciona otros problemas relacionados n.º 456 y n.º 789 para un contexto adicional.

Agregar el mensaje de confirmación

Puede escribir mensajes de compromiso usando el -metro indicador seguido del mensaje de confirmación entre comillas (opcional pero recomendado).

El -metro flag es ideal para mensajes de confirmación breves, que normalmente incluyen el tipo y la descripción.

Por ejemplo:

git commit -m "tarea: Cambiar linter a ESlint"

Sin embargo, cuando su mensaje de confirmación requiere más detalles, como un cuerpo y un pie de página, será mejor que escriba la confirmación en un editor de texto o IDE.

Alternativamente, puede escribir mensajes de compromiso largos en un archivo de texto y usar el --archivo marca para especificar los mensajes de compromiso como el contenido del archivo de texto.

Por ejemplo:

git commit --file commit_message.txt

Cuando ejecute el comando anterior, git usará el contenido del archivo como mensaje de confirmación.

También puede decirle a git que abra su editor predeterminado para escribir un mensaje más largo. Si tiene configurada la variable de entorno GIT_EDITOR o EDITOR, git abrirá ese programa cuando ejecute un simple git cometer dominio.

Por qué debería escribir buenos mensajes de compromiso

Escribir buenos mensajes de confirmación es crucial para una colaboración eficaz y el mantenimiento del código. Los mensajes claros y descriptivos ayudan a comprender, depurar y revisar el código. Incluso pueden contribuir a la documentación del proyecto o las notas de la versión.

Permiten el intercambio de conocimientos, la incorporación fluida y el control de versiones de soporte. Dar prioridad a los mensajes de confirmación de calidad mejora los procesos de desarrollo y garantiza la capacidad de mantenimiento de la base de código.