Guía de Implementación de GitFlow

GitFlow es un modelo de ramificación de Git que define un flujo de trabajo estricto diseñado en
torno al lanzamiento de versiones. Es ideal para proyectos con un ciclo de lanzamiento
programado.

Ramas Principales
GitFlow utiliza dos ramas principales de larga duración:
1. main (o master ): Esta rama almacena el historial oficial de lanzamientos. Solo contiene
código de producción estable y etiquetado con versiones.
2. develop : Esta es la rama de integración para las funcionalidades. Contiene el código más
reciente con las últimas funcionalidades desarrolladas que se incluirán en el próximo
lanzamiento.

Ramas de Soporte
Además de las ramas principales, GitFlow utiliza varias ramas de soporte con un tiempo de vida
limitado:
1. feature/* (Ramas de Funcionalidad):
Propósito: Desarrollar nuevas funcionalidades.
Se ramifican desde: develop .
Se fusionan de nuevo en: develop .
Convención de nombres: feature/<nombre-descriptivo-funcionalidad> o
feature/<JIRA-ID>-<nombre-descriptivo> .
Manejo: Una rama por cada funcionalidad. Un desarrollador (o un par) trabaja en su
propia rama de funcionalidad.
2. release/* (Ramas de Lanzamiento):
Propósito: Preparar un nuevo lanzamiento de producción. Permite la corrección de
errores menores y la preparación de metadatos para el lanzamiento (número de
versión, etc.).
Se ramifican desde: develop (cuando develop está lista para un lanzamiento).
Se fusionan de nuevo en: main (para el lanzamiento) y develop (para incorporar
correcciones).
Convención de nombres: release/<numero-version> (ej. release/v1.2.0 ).
Manejo: Una vez creada, no se añaden nuevas funcionalidades a esta rama, solo
correcciones de errores, documentación y tareas orientadas al lanzamiento.
3. hotfix/* (Ramas de Corrección Urgente):
Propósito: Corregir errores críticos en producción de forma rápida.
Se ramifican desde: main (desde la etiqueta de la versión en producción que tiene el
error).
Se fusionan de nuevo en: main y develop (o la release actual si existe).
Convención de nombres: hotfix/<descripcion-corta> o hotfix/<JIRA-ID>-
<descripcion-corta> o hotfix/<numero-version-corregida> (ej. hotfix/v1.2.1 ).
Manejo: Se crean solo cuando es necesario parchear una versión de producción
existente.

Pasos para Implementar GitFlow desde Cero

1. Inicializar el Repositorio Git:
Si no tienes un repositorio: git init en la carpeta del proyecto.
Crea un repositorio remoto (ej. en GitHub, GitLab, Azure DevOps).
 Conecta tu repositorio local al remoto: git remote add origin
<URL_DEL_REPOSITORIO_REMOTO> .
2. Crear la Rama main :
Por defecto, Git crea la rama master o main . Asegúrate de que se llame main (si
prefieres ese estándar).
Si necesitas renombrarla: git branch -m master main .
Realiza un commit inicial si es necesario: git commit --allow-empty -m "Initial
commit" .
Sube la rama main : git push -u origin main .
3. Crear la Rama develop :
Crea la rama develop a partir de main : git checkout -b develop main .
Sube la rama develop : git push -u origin develop .
A partir de ahora, develop será la rama base para el desarrollo diario.
4. Configurar Ramas Protegidas (en el servidor Git):
Protege las ramas main y develop para que no se pueda hacer push directo. Todos
los cambios deben pasar por Pull Requests (PRs) / Merge Requests (MRs).
5. Flujo de Trabajo para Nuevas Funcionalidades:
Un desarrollador toma una tarea/funcionalidad.
Actualiza su rama develop local: git checkout develop && git pull origin develop .
Crea una rama de funcionalidad: git checkout -b feature/nombre-funcionalidad
develop .
Desarrolla la funcionalidad en esta rama, haciendo commits regularmente.
Cuando la funcionalidad está completa:
Sube la rama de funcionalidad: git push -u origin feature/nombre-
funcionalidad .
Crea un Pull Request (PR) desde feature/nombre-funcionalidad hacia develop .
El equipo revisa el PR.
Una vez aprobado, se fusiona el PR en develop .
Se elimina la rama de funcionalidad (local y remota):
git branch -d feature/nombre-funcionalidad
git push origin --delete feature/nombre-funcionalidad
6. Flujo de Trabajo para un Lanzamiento ( release ):
Cuando develop tiene suficientes funcionalidades listas para un lanzamiento y está
estable:
Crea una rama de lanzamiento desde develop : git checkout -b release/vX.Y.Z
develop .
Sube la rama de lanzamiento: git push -u origin release/vX.Y.Z .
En esta rama solo se hacen correcciones de errores (bugs), se genera
documentación y se actualizan metadatos (versión). No se añaden nuevas
funcionalidades.
Las correcciones hechas en release/vX.Y.Z se fusionan de vuelta a develop
regularmente para que develop también las tenga.
Cuando la rama de lanzamiento está lista y probada (QA):
Fusiona release/vX.Y.Z en main :
git checkout main
git merge --no-ff release/vX.Y.Z (el --no-ff asegura que siempre se
cree un commit de merge, útil para el historial).
git push origin main
Etiqueta el commit en main con la versión: git tag -a vX.Y.Z -m "Release
version X.Y.Z"
 git push origin vX.Y.Z (o git push --tags )
Fusiona release/vX.Y.Z de vuelta en develop (para asegurar que cualquier
corrección hecha en la rama de release también esté en develop ):
git checkout develop
git merge --no-ff release/vX.Y.Z
git push origin develop
Elimina la rama de lanzamiento:
git branch -d release/vX.Y.Z
git push origin --delete release/vX.Y.Z
7. Flujo de Trabajo para Correcciones Urgentes ( hotfix ):
Si se descubre un error crítico en producción (en main ):
Crea una rama de hotfix desde main (desde la etiqueta de la versión afectada):
git checkout -b hotfix/descripcion-corta main (o git checkout -b
hotfix/vX.Y.Z+1 vX.Y.Z )
Sube la rama de hotfix : git push -u origin hotfix/descripcion-corta .
Realiza la corrección y haz commit.
Cuando la corrección está lista y probada:
Fusiona hotfix/descripcion-corta en main :
git checkout main
git merge --no-ff hotfix/descripcion-corta
git push origin main
Etiqueta el commit en main con la nueva versión de parche: git tag -a
vX.Y.Z+1 -m "Hotfix version X.Y.Z+1"
git push origin vX.Y.Z+1
Fusiona hotfix/descripcion-corta en develop (o en la rama release activa si
existe, para asegurar que la corrección también esté allí):
git checkout develop
git merge --no-ff hotfix/descripcion-corta
git push origin develop
Elimina la rama de hotfix :
git branch -d hotfix/descripcion-corta
git push origin --delete hotfix/descripcion-corta

Diagrama Visual del Flujo de Trabajo (Mermaid)

gitGraph
commit id: "Initial"
branch develop
commit id: "dev-A"
commit id: "dev-B"

branch feature/user-auth
checkout feature/user-auth
commit id: "feat-auth-1" type:HIGHLIGHT
commit id: "feat-auth-2" type:HIGHLIGHT
checkout develop
merge feature/user-auth id:"merge-auth" tag:"dev-C (auth)"

branch feature/payment-gateway
checkout feature/payment-gateway
commit id: "feat-pay-1" type:HIGHLIGHT
commit id: "feat-pay-2" type:HIGHLIGHT
checkout develop
merge feature/payment-gateway id:"merge-pay" tag:"dev-D (payment)"
 branch release/v1.0.0
checkout release/v1.0.0
commit id: "prep-release-1" type:NORMAL
commit id: "fix-bug-release" type:REVERSE

checkout main
merge release/v1.0.0 id: "RELEASE v1.0.0" tag: "v1.0.0"

checkout develop
merge release/v1.0.0 id: "merge-release-fixes"

checkout main
branch hotfix/v1.0.1
checkout hotfix/v1.0.1
commit id: "critical-fix" type:REVERSE
checkout main
merge hotfix/v1.0.1 id: "HOTFIX v1.0.1" tag: "v1.0.1"
checkout develop
merge hotfix/v1.0.1 id: "merge-hotfix-dev"

checkout develop
commit id: "dev-E"
branch feature/new-report
checkout feature/new-report
commit id: "feat-report-1" type:HIGHLIGHT
checkout develop
merge feature/new-report id:"merge-report" tag:"dev-F (report)"

Documento para el Equipo: Política de Trabajo

con Git y GitFlow
Asunto: Implementación de GitFlow y Política de Uso de Git
Este documento describe la metodología GitFlow que adoptaremos para la gestión de nuestro
código fuente, junto con las convenciones y políticas asociadas. El objetivo es estandarizar
nuestro flujo de trabajo, mejorar la colaboración y asegurar la estabilidad de nuestros
ambientes.

1. Introducción a GitFlow
GitFlow es un modelo de ramificación para Git que nos ayudará a gestionar lanzamientos de
software de manera organizada. Define ramas específicas para funcionalidades, preparación de
lanzamientos y correcciones urgentes.
Rama main : Contiene el código de producción. Cada commit en main es una nueva
versión y está etiquetado.
Rama develop : Es la rama principal de desarrollo. Contiene el código con las últimas
funcionalidades integradas, listo para el próximo lanzamiento.

2. Convenciones de Nombres de Ramas

Es crucial seguir estas convenciones para mantener la claridad y la automatización.
Rama principal de producción: main
Rama principal de desarrollo: develop
Ramas de Funcionalidad: feature/<tipo-issue>/<issue-id>-<descripcion-corta>
Ejemplos: feature/task/JIRA-123-login-con-oauth , feature/bug/JIRA-124-corregir-
formato-fecha
<tipo-issue> : task , bug , story , etc. (según su gestor de tareas).
<issue-id> : Identificador de la tarea/historia/bug (ej. JIRA-123, Trello-45).
 <descripcion-corta> : En minúsculas, separada por guiones.
Ramas de Lanzamiento: release/<version>
Ejemplo: release/v1.0.0 , release/v2.3.1
Ramas de Corrección Urgente (Hotfix): hotfix/<version> o hotfix/<issue-id>-
<descripcion-corta>
Ejemplo: hotfix/v1.0.1 , hotfix/JIRA-125-vulnerabilidad-login

3. Estándares de Commits (Conventional Commits)

Adoptaremos "Conventional Commits" para mensajes de commit claros y consistentes. Esto
facilita la automatización de la generación de changelogs y el seguimiento del historial.
Formato del Mensaje de Commit:

<tipo>[ámbito opcional]: <descripción>

[cuerpo opcional]

[pie opcional]

<tipo> : Indica la naturaleza del cambio. Tipos comunes:

feat : Una nueva funcionalidad para el usuario.
fix : Una corrección de error para el usuario.
docs : Cambios solo en la documentación.
style : Cambios que no afectan el significado del código (espacios, formato, puntos y
comas faltantes, etc.).
refactor : Un cambio de código que no corrige un error ni añade una funcionalidad.
perf : Un cambio de código que mejora el rendimiento.
test : Añadir pruebas faltantes o corregir pruebas existentes.
build : Cambios que afectan el sistema de compilación o dependencias externas (ej.
gulp, npm).
ci : Cambios en nuestros archivos y scripts de configuración de CI (ej. GitHub Actions,
Travis).
chore : Otros cambios que no modifican el código fuente o las pruebas (ej. actualizar
dependencias, tareas de grunt).
revert : Revierte un commit anterior.
[ámbito opcional] : Especifica el lugar del codebase afectado por el cambio (ej. auth ,
payments , ui ).
<descripción> : Resumen conciso del cambio en imperativo presente (ej. "añadir endpoint
de login" en lugar de "añadido endpoint de login").
[cuerpo opcional] : Explicación más detallada del cambio.
[pie opcional] : Para información adicional como BREAKING CHANGE: o referencias a
issues ( Closes #123 ).
Ejemplos:

feat(auth): implementar autenticación OAuth2 con Google

Añade la posibilidad de que los usuarios inicien sesión utilizando sus cuentas de Goog
Esto incluye nuevas dependencias y configuraciones en el backend.

Closes JIRA-123

fix(checkout): corregir cálculo de impuestos en el carrito

 El cálculo de impuestos no consideraba correctamente las exenciones fiscales
para ciertos productos. Este commit ajusta la lógica para aplicar
las exenciones correctamente.
Refs JIRA-101

4. Flujo de Trabajo Paso a Paso para Desarrolladores

1. Sincronizar develop : Antes de empezar una nueva tarea, asegúrate de tener la última
versión de develop :

git checkout develop

git pull origin develop

2. Crear Rama de Funcionalidad: Crea una nueva rama para tu tarea desde develop :

git checkout -b feature/task/JIRA-XXX-nombre-funcionalidad develop

3. Desarrollar y Hacer Commits:

Trabaja en tu funcionalidad en esta rama.
Realiza commits pequeños y frecuentes usando Conventional Commits:

git add .
git commit -m "feat(module): describir el cambio"

4. Mantener la Rama Actualizada (Opcional, pero recomendado para ramas de larga

duración):
Periódicamente, integra los últimos cambios de develop en tu rama de funcionalidad
para evitar conflictos grandes al final:

git fetch origin develop

git rebase origin/develop # O git merge origin/develop

(Discutir como equipo si prefieren rebase o merge para actualizar ramas de feature.
Rebase mantiene un historial más limpio).
5. Subir la Rama de Funcionalidad: Cuando la funcionalidad esté lista (o para hacer
backup/colaborar):

git push -u origin feature/task/JIRA-XXX-nombre-funcionalidad

6. Crear un Pull Request (PR):

Ve a la plataforma Git (GitHub, GitLab, Azure DevOps).
Crea un PR desde tu rama feature/... hacia develop .
Asegúrate de que el título y la descripción del PR sean claros. Enlaza el issue de JIRA.
Asigna revisores.
7. Revisión de Código y Discusión:
Los revisores comentarán el PR.
Realiza los cambios solicitados en tu rama de funcionalidad y sube los nuevos commits.
El PR se actualizará automáticamente.
8. Fusionar el PR:
Una vez aprobado y todas las comprobaciones (CI) pasen, el PR se fusiona en develop .
 Preferiblemente, usar "Squash and merge" o "Rebase and merge" para mantener el
historial de develop limpio (esto es una política a definir por el equipo). Si se usa
"Squash and merge", asegurar que el mensaje del commit resultante siga Conventional
Commits.
9. Eliminar la Rama de Funcionalidad:
Después de fusionar el PR, elimina tu rama local y remota:

git checkout develop

git branch -d feature/task/JIRA-XXX-nombre-funcionalidad
git push origin --delete feature/task/JIRA-XXX-nombre-funcionalidad

5. Asignación de Ramas a Ambientes

Ambiente de Desarrollo:
Rama Git: develop
Actualización: Continua. Cada vez que un PR de funcionalidad se fusiona en develop ,
se puede desplegar automáticamente (o manualmente) en el ambiente de desarrollo.
Propósito: Integración de funcionalidades, pruebas internas del equipo de desarrollo.
Ambiente de QA (Pruebas de Calidad):
Rama Git: release/<version> (ej. release/v1.2.0 )
Actualización: Cuando se decide preparar un lanzamiento, se crea una rama
release/* desde develop . Esta rama se despliega en QA.
Propósito: Pruebas exhaustivas por parte del equipo de QA, UAT (User Acceptance
Testing). Solo se aplican correcciones de errores en esta rama.
Ambiente de Producción:
Rama Git: main
Actualización: Cuando una rama release/* es aprobada por QA y está lista para
producción, se fusiona en main y se etiqueta con una versión. Esta versión etiquetada
se despliega en producción.
Propósito: Servir la aplicación a los usuarios finales. Solo código estable y probado.
Hotfixes: Si se necesita una corrección urgente en producción, se crea una rama
hotfix/* desde main , se corrige, se prueba (idealmente en un entorno de
staging/QA rápido) y se fusiona de nuevo en main y develop .

6. Políticas para Pull Requests (PRs)

Obligatoriedad: Todos los cambios destinados a develop , release/* , y main (a través de
release o hotfix ) DEBEN pasar por un PR. No se permiten pushes directos a estas ramas.
Revisores:
Se requiere al menos una aprobación de otro desarrollador del equipo.
Para cambios críticos o complejos, se pueden requerir dos aprobaciones.
Título y Descripción:
El título del PR debe ser claro y seguir el formato de Conventional Commits (ej.
feat(auth): añadir login con Google ).
La descripción debe explicar QUÉ cambia, POR QUÉ se cambia y CÓMO se probó.
Debe enlazar al issue/tarea correspondiente en el sistema de gestión de proyectos
(JIRA, Trello, etc.).
Comprobaciones Automatizadas (CI):
Todas las comprobaciones de Integración Continua (CI) deben pasar antes de que un
PR pueda ser fusionado (ej. linters, tests unitarios, tests de integración, build).
Conflictos de Fusión: El autor del PR es responsable de resolver cualquier conflicto de
fusión con la rama destino antes de que el PR pueda ser fusionado.
 Estrategia de Fusión:
Se recomienda usar "Squash and merge" para fusionar PRs de feature en develop .
Esto mantiene el historial de develop limpio con un solo commit por funcionalidad. El
mensaje del commit "squashed" debe seguir el estándar de Conventional Commits.
Para fusionar release en main y develop , y hotfix en main y develop , se usará
"Create a merge commit" (con la opción --no-ff si se hace localmente) para
preservar el historial de estas ramas importantes.
Tamaño del PR: Intentar mantener los PRs pequeños y enfocados en una sola funcionalidad
o corrección. PRs grandes son difíciles de revisar.

7. Política Interna de Trabajo con Git

Reglas Claras:
i. Commit Temprano, Commit Frecuente: Guarda tu trabajo regularmente con commits
atómicos y bien descritos.
ii. Mensajes de Commit Significativos: Sigue el estándar de Conventional Commits.
iii. No Push Directo: Nunca hagas push directo a main o develop . Siempre usa PRs.
iv. Sincronización Regular: Mantén tus ramas locales main y develop actualizadas con el
repositorio remoto ( git pull origin develop ).
v. Actualiza tu Feature Branch: Antes de crear un PR, o durante el desarrollo de
funcionalidades largas, considera actualizar tu rama de funcionalidad con los últimos
cambios de develop para minimizar conflictos ( git rebase develop o git merge
develop ).
vi. Elimina Ramas Fusionadas: Después de que tu PR sea fusionado, elimina tu rama de
funcionalidad tanto localmente como en el remoto.
vii. Resuelve Conflictos Localmente: Si tienes conflictos de fusión, resuélvelos en tu rama
local antes de hacer push o actualizar el PR.
viii. Un Desarrollador por Feature Branch (Generalmente): Para evitar conflictos y facilitar
la gestión, una rama de funcionalidad debería ser trabajada principalmente por un
desarrollador. El trabajo en pareja es una excepción bienvenida.
Revisiones de Código (Code Reviews):
i. Constructivas y Respetuosas: El objetivo es mejorar la calidad del código y compartir
conocimiento, no criticar.
ii. Enfoque: Revisar la lógica, funcionalidad, adherencia a estándares de codificación,
legibilidad, rendimiento, seguridad y cobertura de pruebas.
iii. Comprensión: El revisor debe esforzarse por entender el propósito y la implementación
del cambio. Si algo no está claro, pregunta.
iv. Prontitud: Intentar revisar los PRs asignados en un tiempo razonable para no bloquear
a otros compañeros.
v. El Autor Responde: El autor del PR debe responder a los comentarios y realizar los
cambios necesarios.
Sugerencias de Automatización:
i. Hooks de Git (Husky):
Implementar Husky para gestionar hooks de Git fácilmente.
pre-commit : Ejecutar linters (ESLint, Prettier, Stylelint), formateadores de código y
quizás tests unitarios rápidos antes de permitir un commit. Esto asegura que el
código cumpla con los estándares antes de ser subido.
commit-msg : Usar Commitlint para validar que los mensajes de commit sigan el
estándar de Conventional Commits.
pre-push : Ejecutar el conjunto completo de tests (unitarios, integración) antes de
permitir un push a una rama remota.
ii. Integración Continua (CI):
 Configurar un pipeline de CI (GitHub Actions, GitLab CI, Jenkins, Azure Pipelines)
que se active en cada push a cualquier rama y en la creación/actualización de PRs.
Tareas del CI:
Instalar dependencias.
Ejecutar linters y formateadores.
Ejecutar todos los tests (unitarios, integración, E2E).
Construir la aplicación.
(Opcional) Generar un informe de cobertura de código.
(Opcional) Realizar análisis estático de seguridad.
iii. Despliegue Continuo (CD) (Opcional, pero recomendado):
Ambiente de Desarrollo: Despliegue automático a desarrollo tras cada merge a
develop .
Ambiente de QA: Despliegue automático (o manual con un clic) a QA tras la
creación de una rama release/* o tras cada push a una rama release/* .
Ambiente de Producción: Despliegue manual (con un clic, tras aprobación) o
automático tras fusionar a main y etiquetar una versión.