3 razones por las que debería utilizar compromisos convencionales

Introducción

Como programador, puedes desarrollar una aplicación, una biblioteca, un microservicio o un monorepo lleno de servicios y bibliotecas o (¡el cielo no lo quiera!) un enorme monolito. No importa el tipo de aplicación que desarrolles, si "lo haces bien" utilizarás algún control de versiones (el 90% de las veces será con git).

La pregunta es: ¿cómo se gestiona el historial de versiones? ¿Cómo se informa de la corrección de un error, de la adición de una función, de una tarea realizada en el área de trabajo o incluso de un cambio de última hora? Y lo que es más importante, ¿cómo de fácil es verlo?

Compromisos convencionales es un enfoque estandarizado para el control de versiones que mejora la claridad, la coherencia y la colaboración entre desarrolladores. En este artículo explicaremos qué son los Conventional Commits, cómo funcionan y cuáles son las tres principales ventajas de su uso.

¿Qué aspecto tienen los mensajes Git sin normas?

standard_commit_example

La imagen de arriba ilustra una secuencia de commit git común. Tiene una línea clara y singular, lo cual es bueno, pero deja muchas preguntas sin respuesta. ¿Qué podemos deducir de los mensajes de confirmación? ¿Qué significa fix path ¿Qué significa? ¿Qué ruta? ¿En qué componente?

No se puede responder a eso simplemente mirando el historial de commits.

Tampoco puede hacerlo una máquina. Recuérdalo para más adelante.

¿Cómo es el compromiso convencional?

Comparativamente, este es el aspecto de los mensajes de confirmación según las normas de confirmación convencionales:

conventional_commit_example

Con sólo mirar los dos primeros datos de cada commit, ya aprendemos mucho. Yendo de abajo a arriba, podemos ver que se añadió una característica al componente fab se ha corregido algo en la tipografía, se ha añadido una función al selector de fecha, se ha realizado alguna tarea en el componente docs, otra característica relacionada con accordion itemy así sucesivamente.

¿No está de acuerdo en que nuestros comunicados son ahora más claros y descriptivos sobre los cambios en cada empuje?

Pero los desarrolladores no suelen pasar mucho tiempo mirando los mensajes de commit, ¿verdad? Veamos el verdadero poder de los Conventional Commits.

Ventajas del uso de commits convencionales**

Los commits convencionales tienen tres ventajas principales: los registros de cambios autogenerados, la autoversión y la mejora de la comunicación en equipo.

1. Registro de cambios generado automáticamente

Existen muchas herramientas que pueden generar un registro de cambios según los commits convencionales. Un registro de cambios tiene este aspecto:

vivids_auto_generated_changelog

¿Se ha dado cuenta de que el estándar Conventional Commit ya convierte los envíos regulares en un registro de cambios fácil de leer? Incluso lo divide en versiones con fechas para rastrear cualquier nueva característica y corrección de errores.

¿Cómo puede saber la versión? Esta es la siguiente ventaja.

2. Versionado automático según SemVer

La norma Conventional Commit tiene la siguiente estructura:

{type}({scope}): {description}

La dirección tipo es el tipo de cambio que se ha realizado. Hay 3 tipos principales: características, correcciones o tareas.

El sitio ámbito se refiere a lo que se ve afectado por este cambio. Puede ser un componente, una biblioteca, una aplicación o un servicio.

En descripción describe más específicamente lo que se ha cambiado.

Eso es lo esencial. No voy a aburrir con las especificaciones completaspero sugiero leerlo. Es corto y tiene sentido.

Entonces, ¿cómo nos ayuda esto con el versionado?

SemVer es una forma de versionar nuestro software. La versión se compone de 3 dígitos: X.Y.Z.

X se llama MajorY se llama Minory Z se llama Patch.

Cuando haces un cambio de ruptura, subes una versión mayor. Eso significa que la interfaz de este ámbito cambió.

Cuando se añade una nueva función (sin romper las existentes), se eleva una versión menor.

Cuando se arregla algún fallo sin que sea una característica y sin romper nada, se sube una versión de parche.

¿Ve adónde queremos llegar?

Ahora una máquina puede leer nuestros commits y decidir qué versión debe recibir nuestro ámbito.

Y no tienes que hacerlo tú mismo. Debido a que Conventional Commits es un estándar, existen muchas herramientas que proporcionan auto changelog, auto versioning, y por lo general ambos.

Una de estas herramientas es release-pleaseque también tiene una práctica acción github.

Fomentar una mejor comunicación en el equipo

Además de que los mensajes de confirmación son más legibles, definir la estructura nos da algo más. Da contexto al mensaje de confirmación. Incluso si la descripción es mehporque el tipo de confirmación y su alcance se entienden bien, el lector puede al menos anticipar lo que viene.

Mira este ejemplo:

standarized_commits_example

He aquí un intento de normalización. Sin embargo, una persona que lo mire no puede entender qué tipo de cambio se ha realizado (¿se trata de una corrección o de una funcionalidad?) ni a qué componente. Tampoco se puede deducir de esto un registro de cambios.

Si cambiamos esto un poco, se verá así:

fix(button): verified 48 done and fixed 3 (#172/vivid-103)
feat(button): verified 2 and added demo example (#172/vivid-103)
chore(dialog): fixed 1/5 (font) (#172/vivid-103)

Esto no es mucho mejor, porque la descripción no es descriptiva.

Por otra parte, si uno tiene que escribir el commit con fix(button): {description} es menos probable que esta persona escriba tal descripción. Es más probable que una persona describa el fix o feat hecho en el button.

Como de costumbre, tener algunas normas ayuda a la gente a hacer mejor las cosas. Es algo así como la teoría de la ventana rota.

Pruébalo. A ver qué pasa.

Ejemplo de producción: Mensaje de compromiso estándar de Vivid

Estamos utilizando Conventional Commits en el sistema de diseño de Vonage, Vivid.

Nos ayuda a generar nuestro registro de cambios y registro de versiones y determinar automáticamente la versión de lanzamiento.

Además, nuestros mensajes de confirmación son mucho mejores desde entonces.

Pero nuestra aplicación convencional de commits no está en todos y cada uno de los commits. Durante el desarrollo, un desarrollador puede añadir tantos commits como quiera con cualquier mensaje.

Sin embargo, cuando alguien crea un pull request (PR), imponemos un Conventional Commit en el título del pull request:

github_commit_title_linter

Una acción obligatoria de github que verifica el título de nuestro PR sigue a Conventional Commits

Hemos añadido otra norma que nos ayuda a conectar el commit con un ticket de JIRA. Cada título PR termina con (VIV-XXX) donde XXX es el número de incidencia. Por ejemplo:

fix(disabled): adds a consistent cursor to disabled elements (VIV-999)

Finalmente, en nuestro registro de versiones, el VIV-XXX se convierte en un enlace a JIRA:

convetional_commits_with_jira_links

Finalmente, cuando se fusiona un PR, el título del PR se establece como el commit. Usamos squash + merge para que todo el historial de confirmaciones se elimine de la rama main rama y sólo queda el commit convencional. Se ve así:

github_squash_and_merge_button

Si una pull request tiene más de un cambio (más de una corrección o función), siempre se pueden añadir en los comentarios de la confirmación de fusión. Lo hacemos así:

pr_with_multiple_commits

La herramienta Conventional Commit (en nuestro caso, release-please) considerará estos comentarios como si formaran parte del mensaje.

De esta forma, adoptamos un enfoque relativamente lax con respecto a los mensajes de confirmación, asegurándonos de que el último paso sea describir realmente el cambio.

Resumen

Los commits convencionales nos ofrecen dos ventajas directas: un registro de cambios autogenerado y un versionado automático.

Hay muchas formas de alcanzar estos objetivos.

Una de estas herramientas es Bola de playa. Esta herramienta utiliza una CLI que genera un archivo JSON en lugar de leer el historial de git. La gran ventaja aquí es que es mucho más fácil cambiar el historial si uno cometió un error (cambiar el historial de git puede ser bastante lioso...).

Aparte de estos dos beneficios claros e inmediatos, afirmo que también ayuda a animar a la gente a escribir mejores mensajes de compromiso.

Puede que me equivoque 🙂 Házmelo saber en nuestro Slack de la comunidad de Vonage o envíanos un mensaje en X, antes conocido como Twitter.

Recursos adicionales

Sistemas de diseño: Lecciones de Vivid

Cómo las pruebas de software pueden contribuir a la comunicación

Introducción a Git