Integración
Pasos anteriores
Antes de leer la documentación de integración, debes elegir un esquema de versionado para tu proyecto. A continuación, consulta la guía de integración paso a paso de tu esquema.
En la instancia de integración, se fusionan todos los cambios en la misma rama develop o entrega. En Studio, esta integración se realiza a través de merge requests (también denominadas MR).
Cuando se crea una rama, comienza a partir de la última confirmación de la rama de origen. Mientras esta nueva rama evoluciona, la rama fuente puede seguir recibiendo cambios. En el momento de la fusión, Git analiza el punto común más reciente entre las dos ramas (conocido como ancestro común) y, a partir de ahí, determina qué cambios introdujo cada rama. Es decir, Git no compara rama contra rama antes de una fusión, sino que compara rama contra un ancestro común de commit. Esto permite calcular las diferencias entre ramas y aplicar los cambios.
Lee los estándares de creación para aprender a crear correctamente un merge request y, a continuación, consulta los estándares a aplicar durante un merge para aprender cuáles son los fundamentos del merge y cómo fusionar ramas en cada esquema de versionado.
Estándares de creación de merge requests
Dado que las MR no muestran las diferencias ni el historial de commits en Studio, la descripción del MR se convierte en la principal fuente de información sobre lo que se está integrando. Por lo tanto, es esencial mantener una convención clara y detallada para facilitar la revisión, la trazabilidad y las pruebas en el equipo.
Sigue los pasos que se indican a continuación al crear nuevos merge requests en Studio:
El título debe incluir el tipo de cambio (feature, fix, etc.), el nombre de la funcionalidad y, si aplica, el número de ticket. Ejemplo: [FEATURE] Biometric Login - Ticket #1234 Description.
La descripción debe incluir un breve resumen de lo que se ha hecho, las funcionalidades añadidas, los cambios en las entidades que se almacenan en la base de datos y el desarrollador responsable. Ejemplo:
Includes: Validation by fingerprint. Automatic redirection if session is active. Log of failed attempts (new table). Database changes (essential for release branch merge): Site Param: Value 55 in KEYVALUE Error handler: OnError V01:contents1|S432 Developer in charge: John Doe
Estándares de merge
Aunque cada esquema de versionado tiene sus propias directrices y mejores prácticas de fusión, hay un conjunto de estándares básicos que se aplican a cualquiera de las estrategias de versionado seleccionadas.
Haz merge en las ramas sólo cuando el desarrollo esté completo, probado y validado funcionalmente. Debe representar una unidad de trabajo estable, autónoma y alineada con los requisitos definidos.
No hagas merge en una rama con cambios parciales o en curso, ya que esto puede introducir un comportamiento inesperado, romper otras funcionalidades o dificultar la identificación de errores.
En el caso de ramas feature o hotfix, fusiona sólo cuando:
se resolvieron los conflictos (si los hubo);
los cambios se documentaron adecuadamente (entidades afectadas, impacto en la base de datos si procede, etc.);
la funcionalidad forma parte de la entrega al cliente.
En el caso de las ramas release, fusiona sólo cuando la entrega haya sido aprobada por QA y confirmada para la liberación de producción. A partir de ese momento, la rama puede integrarse en main y develop (en el esquema unificado), o servir de base para la siguiente versión (en el esquema basado en funcionalidades).
Para minimizar los errores al integrar elementos almacenados en la base de datos, debes:
enumerar explícitamente en la descripción de la RM todas las entidades modificadas en la base de datos con sus valores correspondientes (lo que permite al gestor de versiones validar y aplicar manualmente los cambios necesarios); y
comparar cada rama feature con su rama de integración utilizando DeltaComparator para identificar diferencias en entidades no versionadas.
Consulta a continuación los estándares de merge para cada esquema de versionado. A continuación, si surgen conflictos al hacer un merge, lee Resolución de conflictos para saber cómo proceder, en función del esquema seleccionado.
El esquema basado en funcionalidades presenta tres oportunidades de integración diferentes, siendo una de ellas obligatoria. Además, hay dos oportunidades de integración cuando surge un error.
Antes de integrar una rama feature o hotfix en la rama release, se recomienda actualizarla con los últimos cambios de la versión. Para ello, realiza un pull en Studio creando un merge request con la rama release como origen y la rama feature como destino. Aunque no se detecten conflictos, es una buena práctica validar que los cambios de versión están presentes antes de integrarlos. Leer Resolver conflictos en la rama release si este pull presenta conflictos.
Una vez que se cumplan las condiciones funcionales y técnicas definidas previamente (es decir, que el desarrollo esté terminado, probado y confirmado para su entrega), integra los cambios en la rama release mediante un merge request. Si el pull ya se ha ejecutado, este merge no debería generar ningún conflicto.
Importante
Este paso es obligatorio.
Una vez que la versión pase a producción, haz merge a la rama main para mantener una trazabilidad clara de los entregables y tener una imagen de la instancia de producción. Aunque el sistema puede funcionar sin este paso (sobre todo porque la base de datos se actualiza manualmente), esta integración favorece el control de versiones. Este merge no debería generar conflictos.
Corrección de errores: Una vez que se ha desarrollado, probado y validado la corrección de un error productivo, haz merge de la rama hotfix a la rama release y genera un nuevo release a partir de ella. Esto es obligatorio cuando se encuentra un error en producción.
Corrección de errores: Es obligatorio realizar un pull desde esa rama de la versión (con la corrección aplicada) a la siguiente versión activa. Esto garantiza que la próxima versión también contendrá el hotfix. De no hacerlo, se corre el riesgo de volver a lanzar el mismo fallo a producción en la siguiente versión. Este pull puede generar conflictos si se han realizado cambios en el mismo archivo en la rama release.
Importante
No es necesario realizar un pull de la rama main a la rama release antes de integrar ramas feature o hotfix. En este esquema, la rama main no tiene cambios propios ni desarrollo activo, sino que sólo recibe fusiones de release. Por lo tanto, no hay cambios en main que deban incorporarse a la rama release.
El esquema unificado presenta una oportunidad de integración opcional cuando no se detectan errores en producción. Cuando hay errores y se crea un hotfix a partir de la rama release productiva, hay tres oportunidades de merge, que son obligatorias.
Una vez que una versión pasa a producción, haz un merge de la rama release a la rama main para mantener una trazabilidad clara de los entregables y tener una imagen de la instancia de producción. Aunque el sistema puede funcionar sin este paso (sobre todo porque la base de datos se actualiza manualmente), integrarlo favorece el control de versiones. Este merge no debería generar conflictos.
Corrección de errores: Una vez desarrollada, probada y validada la corrección, haz un merge de la rama hotfix a la rama release, y genera una nueva release a partir de ella. Este merge no debería generar conflictos.
Corrección de errores: Realiza un pull de la nueva versión (con la corrección aplicada) a la siguiente rama activa de la versión. Esto garantiza que la próxima versión también contendrá el hotfix. De no hacerlo, se corre el riesgo de volver a lanzar el mismo fallo a producción en la siguiente versión. Este merge puede generar conflictos.
Corrección de errores: Realiza un merge rama release a la rama develop. De esta manera, nuestra rama develop tiene la corrección productiva. Este merge no debería generar conflictos.
Anular una fusión
En determinadas ocasiones, puede ser necesario deshacer una integración. Esto puede ocurrir:
si una función se fusionó por error y no debía formar parte de la versión;
tras una integración se detecta un fallo crítico que impide su entrega; o
una determinada funcionalidad no se incluya en la versión final.
En estos casos, es importante saber qué opciones tenemos para revertir la integración o restaurar el estado anterior de la rama.
Devolver una rama a un punto anterior o anular un merge es técnicamente posible. Sin embargo, debido a la particular implementación del enlace entre Studio y GitLab, no se recomienda hacerlo de forma independiente, ya que implica procesos manuales adicionales que deben ejecutarse cuidadosamente.