Commits de Git fáciles de leer Aprende las reglas PORTADA

Commits de Git fáciles de leer. Aprende las reglas

Compártelo

Crear commits en Git es lo más normal del mundo para todas aquellas personas que se dedican a la programación. Cuando comienzo a crear tutoriales de Git para mis alumnos o lectores siempre recuerdo los comienzos de mi andadura en el desarrollo web. Lo que importaba era crear algo rápido, con «lucecitas» y que fuera más o menos asequible, lo último en lo que pensabas era en que luego tendrías que dedicarte a mantener esa web y le tenías que explicar al cliente qué y cómo lo ibas a realizar.

Poco después, cuando los proyectos empezaban a ser más grandes, la documentación de los mismos era algo imprescindible, porque, aún sabiendo que es algo engorroso, es lo único que tenía ante cualquier duda del cliente y sobre cualquier cambio importante que repercutiera en el posterior precio final.

Commits de Git fáciles de leer Aprende las reglas CAPTURA-2

Una reflexión personal sobre Git

Lo cierto es que Git siempre estuvo ahí, pero como una especie de «copia de seguridad» puntual que hacía de los proyectos para tenerlos a buen recuardo en mi servidor personal.

Ahora bien, cuando el proyecto adquiere unas dimensiones más que considerables. El desarrollo puede durar varios meses y, por supuesto, el equipo ya está formado por unas 5 personas, es cuando entramos en la materia real de Git y en su función real, el control de versiones. Esto es algo imprescindible a la hora de llevar a buen puerto cualquier proyecto, ya que no es posible hacer una reunión diaria comentando todos los cambios importantes por parte de cada uno del equipo y, además, es seguro que nadie usa un bloc de notas para apuntarse los cambios a medida que se van haciendo.

Te voy a decir un pequeño secreto y es que, si Git aún no entró en tu vida y te dedicas al desarrollo web de forma profesional y activa, ten por seguro de que un día llamará a la puerta y lo adoptarás como tu hijo… no, no, mejor aún, él será quien te adoptará a tí y se convertirá en tu máximo confidente y «resolvedor» de trifulcas entre todos los de la casa. Sí eso es 🙂

Entramos en materia: Commit y la imaginación

Uno de los principales escollos que tuve que resolver cuando comencé a trabajar activamente con Git fue la creación de los commits. Esto es:

Soy un desarrollador que siempre está con prisas. Los clientes siempre están prendiendo fuego y yo, con una mano uso la maguera para apagarlos y con el otro programo. No me gusta crear nombre ni en variables porque eso implica dejar de teclear y ponerme a buscar un nombre descriptivo para que cualquiera que lo lea se entere de qué va esa parte del código.

Entonces, ¿qué demonios hago haciendo un párrafo de historia cada vez que hago un cambio importante? ¿Esto no tiene sentido?

Esto es lo primero que se te viene a la cabeza, seguro. Luego, dos semanas después comienzas a ver los resultados de este esfuerzo y es que mientras tú estabas desarrollando el backend en la parte de login, Miguel estaba desarrollando el backen en la parte de registro y los dos cambiastéis un parámetro necesario para la encriptación de la contraseña… Esto ya no es un problema, porque cuando hiciste el merge al día siguiente, viste el commit de Miguel describiéndote exactamente lo que pasó y ya puedes actuar en consecuencia (y esto es solo un pequeño ejemplo).

Cuando se trata de escribir mensajes de confirmación de commits, a todos se nos «esguinza el cerebro». A veces es muy difícil describir un mensaje de confirmación y hacer que tenga sentido. ¿Cómo de extenso debe ser el commit? ¿qué tengo que explicar? ¿hay alguna convención para la creación de los commits?

Y ahí es donde la convención para la creación de commits puede ayudarte. Se trata de un conjunto de reglas escritas no oficiales, pero de alguna manera, constituidas por la comunidad dev para ayudarte a describir un mensaje de confirmación para el commit.

Esto no es un estándar de oro en la industria, algunas empresas lo utilizan y otras tienen su estructura de propia. Al final, lo importante es que sea lo más concisa posible y en muy poco espacio, para que todo el equipo no tenga dudas de ningún tipo de cambio. Consulta siempre con tu equipo de qué forma utilizan estas convenciones antes de comenzar un proyecto con nuevos compañeros, será lo mejor.

La estructura convencional del commit

La estructura básica de los commits convencionales es la siguiente:

<tipo>([ámbito de aplicación opcional]): <descripción breve>

[body opcional]

[footer opcional]

Profundicemos un poco más en el significado de estos elementos.

  • Tipo: Este es un tipo imprescindible. Nos sumergiremos en los tipos en un segundo. Básicamente es expresar qué tipo de cambio se ha realizado.
  • Ámbito de aplicación opcional: Un flag opcional para indicar un ámbito aislado
  • Descripción corta: Tu descripción general para el commit
  • Body opcional: Una descripción más detallada de la confirmación, esto es opcional pero útil para confirmaciones más grandes
  • Footer opcional: Puede indicar los cambios de ruptura y hacer referencia a los problemas por el número de ticket
Commits de Git fáciles de leer Aprende las reglas CAPTURA-1

Tipos de mensaje commit

Bien, echemos un vistazo a los tipos ya que son un aspecto importante aquí y yo creo que lo único que tendrías que aprenderte sí o sí para el correcto desarrollo del control de versiones.

  • build: Cambios que afectan al sistema de construcción como gulp, npm, etc
  • ci: Cambios que afectan a la configuración de CI como Travis, Circle, Actions
  • chore: Otros cambios que no modifican los archivos src o de prueba
  • docs: Cambios sólo en la documentación
  • feat: Una nueva característica
  • fix: Se ha corregido un error
  • perf: cambios en el código que mejoran el rendimiento
  • refactor: Un cambio de código que no es particularmente un error o una nueva característica
  • revert: Revertir una confirmación anterior
  • style: Cambios de estilo como espacios en blanco, formato, puntos y comas)
  • test: Añadir o corregir pruebas

Algunos ejemplos

Veamos algunos ejemplos, ya que permiten comprender mejor lo que ocurre y como se crea un commit en condiciones para un cambio cualquiera.

En el siguiente ejemplo, vemos que se introduce una nueva función en la aplicación. También se indican algunos detalles más en el cuerpo y se hace referencia a un ticket que se puede establecer como #hecho (yo los tickets suelo dejarlos en inglés, ya que tanto en SCRUM como en Kanban se usan estos estados.

feat: devcard con tema de vacaciones 
/** esto es lo imprescindible, el tipo feat, indica que el cambio que se realizó es el añadido de una nueva característica, y la pequeña descripción nos índica cuál es esa nueva característica. A partir de aquí lo que quieras explicar a mayores ya es cosa tuya. Por ejmplo: **/

¡Nuestra DevCard cuenta ahora con un tema de vacaciones tanto para Verano como para Navidad!
También incluye un enlace que apunta al artículo de Martín sobre cómo incrustarla en tu perfil de GitHub.

DD-267 #done

A continuación, puedes ver una confirmación de compilación que sólo afecta a un ámbito específico, la extensión. Actualiza la versión a 3.8.0

build(extension): version 3.8.0
Commits de Git fáciles de leer Aprende las reglas CAPTURA-3

Este, por ejemplo, introduce un cambio de ruptura y se incluye un ! para llamar la atención sobre dichos cambios en los que se solicita una actualización de Node.

chore!: eliminar el Node 6 de la matriz de pruebas

CAMBIO: dejar de lado el Node 6 que llega al final de su vida útil en abril

Este es de tipo CI donde introducimos un nuevo helper de Kubernetes.

ci: utilizar los nuevos helpers de kubernetes

Material de referencia

Si quieres leer más reglas y ejemplos del mundo real, aquí tienes algunos recursos fantásticos.

Y con esto acabamos nuestro resumen de cómo escribir un commit con una descripción útil y eficaz que, aunque cueste un poco al principio y seguramente tengas que releer este artículo un par de veces más, lo asimilarás más pronto que tarde esto me ayudó a que los mensajes de confirmación fueran mucho más fáciles y precisos para mi equipo.

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *