Cómo hacer cambios en un paquete de bPanel4 y compartirlos con los demás

⚠ Antes de nada aviso de que el proceso parece muy largo pero en cuanto lo haces 2 veces lo haces en segundos. También aviso de que pueden darse casos en los que no funcione por varios motivos, relacionados con nombres de ramas, archivos locales, etc, que tienen fácil solución pero que de momento no he documentado. A medida que nos los vayamos encontrando los iré añadiendo.

1. Instalar la versión para desarrollo del paquete

En composer, cuando instalamos un paquete, lo podemos hacer de 2 formas, como paquete de distribución (dist) o de desarrollo (source). La principal diferencia es que cuando instalamos la versión para desarrollo, además de todos los archivos del paquete, nos traeremos también su repositorio de git. Esto nos permitirá hacer cambios localmente y después subirlos al repositorio para que estén disponibles para todos.

⚠ ATENCIÓN, TURRA QUE TE PUEDES SALTAR (A NO SER QUE EL SIGUIENTE PASO TE DE FALLOS):

Para poder trabajar así hay que tener un repositorio de composer (lo tenemos, si estás creando un paquete nuevo habrá que darlo de alta pero es muy fácil), y además, el paquete tiene que tener unos nombres de ramas con algunas características. Como de momento ningún paquete está desarrollado al 100%, todos los paquetes tienen versiones que empiezan por 0. (esto es una convención que se usa normalmente en proyectos Open Source). Para poder hacer lo que viene ahora, la rama sobre la que vayas a trabajar inicialmente debe llamarse exactamente v0. Para entender por qué, y también para ver otras formas de hacerlo, ve a la documentación sobre versiones de paquetes de Composer.

Para instalar la versión de desarrollo de un paquete, hay que especificar la versión como .x-dev, y además, añadir la opción --prefer-source:

composer require <nombre del paquete> v0.x-dev --prefer-source

Por ejemplo:

composer require bittacora/bpanel4-multimedia v0.x-dev --prefer-source

Una vez instalado el paquete, ve a la carpeta donde se ha instalado y ejecuta git status. Deberías ver lo siguiente:

On branch v0
Your branch is up to date with 'origin/v0'.

nothing to commit, working tree clean

Es decir, que el paquete se ha descargado desde la rama v0, y además está actualizada con origin/v0, es decir, la versión de Gitlab. La última línea nos dice además que en los archivos que tienes localmente no hay ningún cambio respecto a esa rama, así que está todo listo para empezar a hacer cambios.

Si ya tenías el paquete instalado, lo mejor es que lo borres y lo vuelvas a descargar con el comando que hemos visto antes.

2. Ejecutar los tests

Antes de empezar a hacer cambios, lo ideal sería que antes de hacer los cambios se ejecuten los tests. De esta forma, es fácil saber si se ha roto algo que ya existía en algún paquete y se evita romper algo en otros proyectos que estén usando el paque te que se va a modificar, y que hagan una actualización para tener la última versión.

IMPORTANTE: Si no tienes 100% claro que tu .env está configurado de forma que no se van a enviar correos a usuarios reales, que no se va a hacer nada en un TPV real, etc, desconecta la conexión de red de tu ordenador antes de ejecutar los tests. Normalmente, durante el desarrollo usamos mailtrap y los entornos de prueba de los servicios externos que necesite el proyecto, pero si no estás seguro al 100% de que no vas a llamar a nada externo, desconecta el ordenador de internet. Al ejecutar los tests se llamará a gran parte de las funciones de los paquetes, y pueden salir correos, hacerse pedidos, etc.

Escribir tests cuesta un poco al principio, y no es obligatorio escribirlos para los paquetes (aunque si muy recomendable), pero ejecutarlos es muy fácil, sólo hay que llamar al siguiente comando desde la raíz del proyecto:

vendor/bin/phpunit

O:

php artisan test

Si todo va bien, deberías ver algo como esto (puede que salgan menos tests, porque dependerá de los paquetes que tengas instalados en el proyecto):

Si salen errores o no se pueden ejecutar, habría que ver según el caso por qué están fallando y corregir los errores, que normalmente vendrán por alguna configuración, extensión de PHP que no está instalada, etc.

Si los tests pasan, entonces puedes modificar el paquete que quieras con más seguridad. El último paso antes de subir los cambios es volver a ejecutarlos para comprobar que no se ha roto nada, pero antes de eso, era necesario saber que no había nada roto de antemano.

3. Preparar el IDE para hacer los cambios

En principio ya podrías hacer los cambios, pero dependiendo del IDE que uses, es posible que el paquete se siga considerando como librería externa y que no tengas autocompletar, ni puedas ver qué líneas has cambiado, etc. Vamos a ver cómo se corrije esto en PHPStorm, y si alguien que use VSCode puede, que documente cómo se haría lo mismo en ese IDE.

3.1. No marcar la carpeta como excluida

Para esto simplemente habrá que desplegar la carpeta vendor/bittacora, hacer clic derecho en la carpeta del paquete, y marcar la opción Mark directory as > Cancel Exclusion.

3.2. Indicar que en esa carpeta hay un repositorio de git

Para esto, habrá que abrir el panel de ajustes (File > Settings) y después ir a Version control > Directory mappings. Desde ahí podrás añadir la carpeta del paquete (en este caso vendor/bittacora/bpanel4-multimedia), y ya podrás ver los cambios resaltados, etc.

4. Hacer los cambios

Por fin está todo preparado para hacer los cambios. En este paso no hay mucho más que decir porque se trata simplemente de hacer los cambios que haya que hacer en el paquete. Lo único que hay que tener en cuenta es que hay que evitar hacer composer update sin ningún argumento, porque podrían sobreescribirse los cambios que estés haciendo. Si se quiere instalar un paquete, se hará como normalmente se hace, es decir composer require XXX y no pasa nada, pero si se quiere actualizar algo, tiene que hacerse también indicando el nombre del paquete, es decir composer update XXX.

Sería muy recomendable que todos los cambios que se hagan en un paquete tengan su correspondiente test, pero hasta que no estemos todos al día con el testing entiendo que es difícil. Aún así puede ser buen momento aprender los básico de PHPUnit y hacer unos tests (aunque sean sencillos) de los cambios del paquete.

5. Volver a ejecutar los tests

Ahora sería buena idea volver a ejecutar los tests para comprobar que no se haya roto nada de lo que ya había antes de los cambios. Si vuelven a pasar, perfecto, puedes seguir adelante, pero si antes pasaban y ahora no, eso quiere decir que has roto algo de otro paquete, y que afectará a los proyectos de otros developers. Como mínimo, creo que sería bueno avisar a los demás para que tengan cuidado, o para poder solucionar los problemas que hayan surgido entre todos, y hacer que el paquete no fuerce a nadie a hacer cambios en su proyecto. Esto puede sonar un poco catastrofista o dramático, pero normalmente, si un test falla, es cuestión de tiempo que el cliente te llame para quejarse precisamente de ese mismo fallo.

Más adelante, cuando tengamos todo este proceso más interiorizado y hayamos avanzado con el testing, iremos añadiendo procesos de integración contínua a los paquetes, para tener un mejor control sobre el código y mejorar poco a poco la calidad.

6. Subir los cambios

Ahora toca compartir las mejoras o ajustes del paquete con los demás. Para hacerlo, hay que subir los cambios al repositorio de gitlab como se haría con cualquier otro proyecto, con un par de pasos adicionales.

Haz el commit como harías normalmente (asegurándote de que estás en la rama v0), haz git push, y después ve al respositorio del paquete en gitlab. Después ve al apartado Code > Tags y fíjate en el número más grande que veas. Como las etiquetas salen ordenadas por fecha normalmente la primera que sale será la que tenga el número de versión más grande. Apúntalo y pulsa en el botón azul de New Tag (arriba a la derecha).

Llegarás a la siguiente pantalla:

Lo primero que debes hacer es poner el campo Create from como en la captura, es decir, en v0. Ahora falta escribir el nombre de la etiqueta, que será el número de versión del paquete. Antes apuntaste el número de versión más alto que había hasta ahora en el paquete, y para etiquetar tus cambios deberás crear una versión nueva. Para hacerlo, debes seguir las reglas del versionado semántico. De forma muy resumida, es suficiente con que sigas estas indicaciones básicas. Suponiendo que el número de versión es vX.Y.Z:

si solo estás subiendo correcciones de errores, o cambios muy pequeños (cambiar un texto, etc), aumenta el tercer número (Z)
si estás añadiendo algo nuevo al paquete, pero los demás podremos usar tu actualización sin modificar nada en nuestros proyectos, aumenta el segundo número (Y) y pon el tercero (Z) a cero.
si estás añadiendo cambios que obligarán a los demás a hacer cambios en su código existente para seguir usando el paquete, aumenta el primer número (X) y pon los otros dos a cero.

Una vez hayas decidido el número de versión, pulsa en create tag y ya habrás creado una nueva versión del paquete, pero falta que nuestro repositorio de composer lo sepa.

ℹ Esto es totalmente opcional, pero para tener un historial de cambios más uniforme, sería interesante que todos siguiésemos esta convención a la hora de escribir los mensajes de los commits. Se llama Conventional Commits, es muy fácil de seguir y permite automatizar la creación de changelogs, números de versiones, etc.

Otro detalle a tener en cuenta, que también es opcional, sería hacer commits que no fuesen muy grandes, si puede ser, un commit por cada cambio del paquete. Esto no quiere decir que para cada línea que toques hagas un commit, sino que si vas a hacer cambios en el módulo de multimedia, separes los cambios en commits individuales, del tipo:

feat: Añadir subida de vídeos al servidor (mp4, etc)

fix: Eliminar archivos temporales que se acumulaban al generar miniaturas

feat: Comprimir imágenes en webp automáticamente

Así es más fácil entender un cambio para los demás (por ejemplo, usando git show <hash del commit> o git blame). Si además del título del commit añades una descripción (ejecutando git commit en vez de git commit -m XXXXXXX) mejor.

7. Añadir la nueva versión del paquete al Composer de Bittacora

En muchos de los paquetes, este paso es automático porque tengo configurado un hook en gitlab para que se actualice automáticamente nuestro composer, incluso hay un canal de discord (Discord Composer Bittacora) en el que saltan notificaciones cada vez que se actualiza un paquete. Para comprobar si el hook está creado, ve al repositorio del paquete en gitlab, y en el menú ve a Settings > Webhooks. Si sale algún hook, no tienes que hacer nada, pero si no sale, avísame y te digo como añadirlo. No lo pongo aquí directamente por no alargar más este tutorial, que ya es bastante largo.

Si no sale ningún hook, aparte de avisarme para configurar uno, también puedes visitar directamente https://composer.bittacora.dev/build.php y se actualizará todo nuestro composer. Es preferible evitarlo porque tarda bastante más y consume muchos recursos del servidor, pero puede usarse sin problema.

8. (Opcional) Usar la versión de distribución del paquete modificado

Por último, si no vas a hacer más cambios en el paquete, puedes dejar instalada la versión de desarrollo, o también borrarlo (asegúrate de que has commiteado y pusheado todos los cambios) y después instalar la versión de distribución del paquete:

composer require bittacora/bpanel4-multimedia ^0.4.9 # El número de versión solo es un ejemplo, tendrías que poner la que has creado antes