Commit semántico: una guía completa para optimizar tu proyecto

Antes de comenzar con el tema principal de este artículo, es interesante aclarar algunos conceptos que son importantes para la comprensión completa del contenido que se presenta a continuación.

¿Qué es commit?

El commit es el registro de los cambios de código en un momento dado. Cuando desarrollas un proyecto, es interesante crear nuevas versiones de los archivos en lugar de cambiar los materiales originales y, con el commit, agregas estos cambios a los repositorios, creando historias lógicas del desarrollo.

En este contexto, cabe mencionar una frase del glosario de Git, una de las principales plataformas de versionado de código del mundo: “toda la historia de un proyecto se representa como un conjunto de commits interrelacionados”.

En Git, debes ingresar los siguientes comandos en la terminal para realizar un commit:

¿Qué es semántica?

Según el diccionario Michaelis, la semántica es la “rama de la lingüística que estudia el significado de las palabras y sus cambios de significado a lo largo del tiempo, así como la representación del significado de las declaraciones”.

En tecnología, la semántica es complementaria a la sintaxis. Mientras que la sintaxis se refiere a la estructura de un programa, la semántica está ligada al significado, a la interpretación del código.

¿Qué es el commit semántico?

Basados ​​en los dos últimos conceptos, podemos decir que el commit semántico es una buena práctica para estandarizar los commits de un proyecto, facilitando la consulta y organización del desarrollador y otros profesionales que necesitarán trabajar en el proyecto. Los commits semánticos contribuyen a la creación de un historial lógico que permite comprender los cambios realizados en la vista del repositorio.

El proyecto Conventional Commits, dedicado a crear un modelo de estandarización para confirmaciones, inspirado en las pautas de Angular Commit Messages Convention, lo describe como: "una especificación para agregar significado legible por humanos y máquinas a los mensajes de confirmación".

Estructura y tipos

El commit semántico puede ser estructurado de las siguientes formas:

Para agilizar la rutina, se puede seguir el modelo sin usar las opciones o hacer pequeños cambios en la estructura según los supuestos de la empresa o del equipo de desarrollo.

• Tipo: especifica la actividad realizada.
• Alcance o scope: parte del código que sufrió la alteración.
• Descripción: lo que se hizo en el commit.
• Cuerpo: detalles sobre lo que se hizo en el commit.
• Pie de página: informa issue, id o task utilizados en la alteración del código sometido a commit.

Abajo encontrarás algunos de los principales tipos que pueden ser incorporados a la rutina.

Valores aceptados de acuerdo con Karma Guidelines:

• fix: solución de un problema.
• feat: incluir un nuevo recurso en la base.
• test: agrega/refactoriza pruebas sin alteración en la producción.
• refactor: refactoriza el código en producción.
• docs: altera la documentación.
• style: altera el formato sin modificar la producción.
• chore: actualiza tareas sin alteraciones de producción.
  

Otros tipos que también pueden ser utilizados son:

• ci: modifica archivos y scripts de configuración de CI.
• build: altera el sistema de compilación o las dependencias externas.
• perf: mejora el desempeño.
• improvement: añade mejoras en la implementación actual sin agregar nuevos recursos o corregir problemas.
• env: modifica archivos de configuración.

Se espera que, al agregar cambios al código que eventualmente puedan afectar el funcionamiento del código, debe insertarse la etiqueta BREAKING CHANGE en el body.

Ejemplos de commits semánticos con el modelo adaptado:

docs(readme): remove incorrect tag from api document

fix(containers): adjust argument of profile function

Especificaciones

Existen algunas especificaciones recomendadas en guidelines (tales como o Karma Guidelines):

• El mensaje debe contener menos de 150 caracteres en total. Usa siempre el modo imperativo;
• La primera línea no puede contener más de 70 caracteres; la segunda línea siempre estará vacía;
• Las otras líneas deben contener hasta 80 caracteres;
• El tipo y alcance siempre debe estar en minúsculas;
• El alcance puede estar vacío en los casos donde se omiten los paréntesis.

Herramientas para ayudar con la creación de los mensajes

Aunque hay una serie de especificaciones para ayudar a crear commits, existen algunas herramientas que pueden ser excelentes aliadas para escribir mensajes.

Commitizen

La biblioteca facilita y optimiza el proceso de creación de confirmaciones basadas en Conventional Commits. Con él, es posible crear scripts que guiarán la creación de mensajes.

Commitlint

La herramienta verifica que el mensaje escrito esté dentro de los estándares definidos, que pueden ser los existentes o completamente personalizados. Si el commit no sigue las reglas, la biblioteca mostrará un error al usuario.

Husky

Con Husky, podemos definir un activador para que otra plataforma realice la verificación del commit, como Commitlint.

¿Por qué aplicar esto en tu proyecto?

La aplicación de la estandarización de commits en sus proyectos contribuirá a la organización del equipo y la comprensión del código por parte de los nuevos desarrolladores. La creación de un historial de lo desarrollado optimiza el trabajo y permite recuperar extractos en caso de cambios no deseados o incorrectos en el código fuente.

Imagina que estás trabajando en un proyecto colaborativo de código abierto. Si todos los involucrados en la construcción del código usaran la premisa de commits semánticos, probablemente los repositorios estarían más organizados y más desarrolladores estarían interesados ​​en participar en el proyecto, ya que entenderían mejor lo que se hace.

Además, hay formas de automatizar el control de versiones de tu código con una herramienta llamada Semantic Release. Explicaremos un poco más sobre esto y cómo funciona a continuación, pero solo para conectarnos con nuestro tema principal. Para que la versión semántica sea efectiva, necesitas que tu proyecto tenga un historial de confirmación descriptivo y muy explicativo.

Releases

Releases son versiones de una aplicación. Para ejemplificar este concepto, podemos usar como ejemplo Angular, que ya ha lanzado una serie de versiones del framework y ahora tiene 15.

En los repositorios, puedes crear releases con notas explicativas, release notes, menciones de los desarrolladores del proyecto, enlaces y otros archivos e información relevante para la versión publicada.

Semantic Release

Semantic Release es una herramienta de automación de flujo de trabajo para el lanzamiento de nuevas versiones de una aplicación y utiliza los commits para determinar cuál es la versión, generar changelog y publicar las actualizaciones. Por regla, Semantic Release utiliza el empadronamiento de Angular Commit Messages Convention, que también es la base para el proyecto de Conventional Commits.

En este artículo, exploramos una guía completa sobre commits semânticos. Aplícalos en tus proyectos y aumenta la productividad de tu equipo. e

¡Éxito!

Referencias

• Git - gitglossary Documentation
• angular/CONTRIBUTING.md at 22b96b96902e1a42ee8c5e807720424abad3082a · angular/angular
• Understanding Semantic Commit Messages Using Git and Angular K arma - Git Commit Msg
• Semantic Commit Messages
• https://www.conventionalcommits.org/en/v1.0.0