Hay una diferencia entre escribir commits y escribir commits entendibles. Y escribir por escribir no ayuda mucho.
Por ello quiero compartir con ustedes algunos tips o consejos acerca de cómo escribir buenos commits para que los ayude en sus proyectos personales o trabajos en equipo.
¿Por qué es importante escribir commits entendibles?
Cuando estamos empezando a escribir commits, no sabemos dar una descripción. Muchas veces lo que escribimos no nos indica que hicimos exactamente, por lo que solemos hacerlo de manera general o cualquier cosa para mantener el cambio en el historial.
Al escribir commits entendibles permite, no solo a ti, sino que también otras personas; entender que se hizo en cada commit, facilita la búsqueda de bugs y hasta el historial del proyecto es ordenado.
Créeme, incluso si nos quedamos sin ideas, hemos llegado a escribir commits de este estilo:
Y eso no ayuda. Por lo que pasamos a la siguiente pregunta.
¿Cómo deberíamos estructurar un commit?
Estructuremos los commits de una manera que se nos haga la vida mas fácil.
Al usar el comando git commit, nos abrirá un editor de texto en la terminal, o editor de codigo, para realizar el commit. Esta manera es cómoda cuando se va a dar una descripción grande.
En el caso de realizar un commit corto y preciso, es mejor utilizar git commit -m \"mensaje\". Lo que va dentro de las comillas es el mensaje que quieras colocar.
Ahora si. Este seria el tipo de estructura para los commits:
Title -> Type : Subject Body Footer
¿De casualidad no te recuerda a la estructura de un correo electrónico? Es bastante similar si lo analizamos bien.
Ahora expliquemos cada uno.
Title
Es el encabezado del mensaje. Aquí se colocará el Type y el Subject del commit.
Type
El Type indica el tipo de commit que estas realizando, como añadir nuevas novedades, reparar un bug o documentar el código.
Los más comunes son:
-
ADD/FEAT: Se agrega una nueva funcionalidad o un nuevo feature.
-
FIX: Solución de un bug.
-
REFACTOR: Refactorización y mejoras.
-
DELETE: Elimina funciones o archivos.
-
DOCS: Cambios en la documentación.
-
TEST: Añadiste un test o aplicaste una refactorización de pruebas. No toca el código principal.
Hay otros que también pueden ser usados:
-
STYLE: Se aplica cuando hay cambios en el formato, comas y puntos faltantes.
-
CHORE: Actualización de tareas en el Build, configuración del admin de paquetes. Sin cambios en el código
Subject:
Indica el mensaje del commit.
La información debe ser precisa, breve y escrita en imperativo, con un máximo de 50 caracteres, iniciar con la letra mayúscula, y no debe terminar en punto.
Y cuando digo en imperativo, me refiero a que el mensaje debe ser escrito en forma de objetivos.
Ejemplo:
-
Limpieza del código.
-
Cierra la puerta.
-
Saca la basura.
Por ultimo, escribirlo en ingles.
No solo porque es una excelente manera para ayudarte a practicar si estas comenzando aprender ingles, sino porque gran parte de la comunidad de programadores escriben en ingles, los códigos se escriben en ingles y ofreces la oportunidad de comunicarte con otros programadores de otro idioma que no sea el español.
Body:
En esta sección del commit se debe explicar única y exclusivamente el qué cambios hubo y el por qué del commit. El texto explicativo se aplica si es necesario. Puede ser escrito también mediante listas con guiones o asteriscos (Aplicando markdown).
Se requiere una linea en blanco entre el Subject y el body para separarlos. Es importante ese espaciado debido a que evita confusiones y se diferencia entre el titulo y la descripción, o si vas a escribir varios párrafos.
En el mensaje cada linea debe contener 72 caracteres como máximo (Ayuda mucho al lector del código).
Footer
En este apartado se coloca el seguimiento de los tickets o Issues. Este apartado es opcional.
En github, si quieres que te marque un Issue como solucionado en vez de ir a la parte gráfica, en este apartado lo automático cuando lo indicas. Solo tienes que colocar el nombre del caso y el numero. Ejemplo: Issue: #5.
Conclusión
Para finalizar con toda la información adquirida, pongamos un ejemplo completo:
ADD: New elements in the page body Se agregaron nuevos elementos al sitio web. Esto permite agregarle mas contenido al sitio para que los usuarios tengan mejor experiencia e interactividad Adding elements like: - Vertical Navbar - Apartado de noticas - Slider de noticias recientes Add: #300 See also: #210, #50