Wiedii — Política de Branching con Git Flow

⚠️ Verificar versiones antes de usar — la versión de git-flow-next documentada aquí puede estar desactualizada. Consultar brew info git-flow-next o git-flow.sh para la versión más reciente. Ver politicas-core.

Se usa git-flow-next con el preset clásico.

Instalación: brew install git-flow-next

Cuándo Git Flow vs GitHub Flow (excepción general)

Git Flow es el default en Wiedii, pero su rama develop solo aporta valor si el proyecto cumple al menos uno de estos criterios. Si no cumple ninguno, la rama de integración es ceremonia sin beneficio y se recomienda GitHub Flow (solo main).

Criterios que justifican Git Flow (mantener develop):

Criterio	Qué problema resuelve develop
Software versionado que terceros consumen fijando versión (librerías, SDKs, CLIs, paquetes publicados)	Separa "lo ya liberado" de "lo que viene"
Se soportan varias versiones en producción simultáneamente	Habilita hotfix/* y support/* sobre versiones viejas
Releases agrupadas con ventana de estabilización	release/* estabiliza antes de taggear
Existe un entorno de staging/preview mapeado a develop	Permite ver/QA los cambios antes de prod

Cuándo se recomienda GitHub Flow (solo main):

Cuando el proyecto reúne este perfil (típico de sitios estáticos, wikis, apps internas, servicios con despliegue continuo):

• Un solo entorno de despliegue (una sola producción; sin staging atado a develop).
• Despliegue continuo: cada merge a main —o cada tag sobre main— va a producción.
• Sin fijado de versión por consumidores (nadie hace pin a proyecto@1.2.0).
• La madurez del contenido/cambios está gobernada aguas arriba (p. ej. el ciclo borrador → maduro → promovido del vault), no por la topología de ramas.
• Cambios de bajo riesgo, corregibles hacia adelante (fix-forward).

Modelo GitHub Flow en Wiedii

main          ← siempre desplegable; única rama de larga vida
feature/*     ← ramas cortas desde main
fix/*         ← fixes desde main

# Flujo de feature en GitHub Flow
git switch main && git pull origin main
git switch -c feature/TK0001-slug
bun commit                         # czg → Conventional Commits + closed #<id>
git push -o merge_request.create \
         -o merge_request.target=main \
         -o "merge_request.title=feat(scope): description [TK0001]"
# Release: taggear main directamente (los tags y SemVer no cambian)
git switch main && git pull
git tag -a 1.2.0 -m "Release 1.2.0" && git push origin 1.2.0

⚠️ GitHub Flow cambia la topología de ramas, NO las reglas core. Siguen vigentes sin excepción: MR obligatorio, nadie mergea su propio MR, main protegida, rebase antes de merge, merge.ff=false, Conventional Commits con closed #<id>, tags sin prefijo v.

Requisitos para adoptar GitHub Flow

1. Documentar la excepción en el repo (CLAUDE.md / CONTRIBUTING.md) y, como altera la relación con el estándar, validarla con quien gobierna las políticas Wiedii — no un drift tácito.
2. Renovate: la rama por defecto del repo debe ser main y renovate.json debe llevar "baseBranchPatterns": ["main"] (ver renovate).
3. Branch protection sobre main (push: solo mantenedores; merge: dev + mantenedores).

La política de Renovate ya contempla este perfil como "proyectos sin gestión de ramas" y lista documentación independiente como ejemplo: GitHub Flow no viola el estándar, es una ruta sancionada para los proyectos que encajan en el perfil de arriba.

---

Inicialización (una vez por clon del repo)

git flow init --preset=classic --defaults

# Wiedii: sin prefijo 'v' en los tags — sobreescribir inmediatamente después del init
git config gitflow.branch.release.tagprefix ""
git config gitflow.branch.hotfix.tagprefix ""

Sin este ajuste, el preset clásico establece tagprefix = v, generando v1.2.0 en lugar de 1.2.0. En Wiedii siempre se usa 1.2.0.

Esto crea: main (producción), develop (integración), con prefijos feature/, release/, hotfix/, support/.

Reglas de ramas

Rama	Propósito	Origen	Se fusiona en
main	Producción — siempre desplegable	—	—
develop	Base de integración	main	—
feature/*	Nueva funcionalidad	develop	develop (via MR)
release/*	Preparación de release	develop	main + develop (via MR)
hotfix/*	Fix urgente en producción	main	main + develop (via MR)
support/*	Soporte de versiones legacy	main	—

Push directo a main/develop: solo los mantenedores del proyecto (rol Maintainer en GitLab). El resto del equipo integra cambios siempre vía MR. Ver branch-protection.

Estrategia de merge

• Actualizar rama desde su padre: git flow update — usa downstreamstrategy = rebase por defecto en el preset clásico (mantiene historia lineal)
• Fusionar hacia el padre: siempre --no-ff (forzado globalmente por merge.ff=false)
• Squash: NUNCA permitido

Flujo de feature (paso a paso)

# 1. Partir desde develop actualizado
git switch develop && git pull origin develop
git flow feature start TK0001-max-tres-palabras

# 2. Trabajar — commits atómicos
git add .
bun commit     # wizard czg → Conventional Commits

# 3. Actualizar desde develop antes del MR (rebase via downstreamstrategy)
git flow update

# 4. Publicar la rama y abrir MR en un solo comando
git flow publish \
  -o merge_request.create \
  -o merge_request.target=develop \
  -o "merge_request.title=feat(scope): description [TK0001]"

NUNCA usar git flow feature finish — hace el merge localmente y saltea la protección de ramas y el CI.

Comandos cortos de git-flow-next

git-flow-next detecta automáticamente el tipo de rama actual:

git flow update    # actualizar rama actual desde su padre (rebase)
git flow publish   # hacer push de la rama actual al remoto
git flow finish    # finalizar la rama actual (⚠️ evitar — usar flujo de MR)
git flow delete    # eliminar la rama actual
git flow rename new-name   # renombrar la rama actual
git flow overview  # estado completo del repo: ramas, ahead/behind, health checks

Push options de GitLab para publish

git-flow-next pasa las opciones -o directamente a git push, que GitLab recibe como push options:

git flow publish -o merge_request.create               # crear MR
git flow publish -o merge_request.target=develop       # rama destino
git flow publish -o "merge_request.title=feat: ..."   # título del MR
git flow publish -o merge_request.merge_when_pipeline_succeeds  # auto-merge al pasar CI

Se pueden persistir en config para que git flow publish siempre cree el MR:

git config gitflow.feature.publish.push-option "merge_request.create"
git config --add gitflow.feature.publish.push-option "merge_request.target=develop"

Flujo de release

git flow release start 1.2.0          # sin prefijo v — nunca
# bump de versión en package.json, actualizar CHANGELOG
git flow publish \
  -o merge_request.create \
  -o merge_request.target=main \
  -o "merge_request.title=chore(release): 1.2.0"

# Después de que el MR se fusione a main — tag y sync a develop:
git tag -a 1.2.0 -m "Release 1.2.0"
git push origin 1.2.0

glab mr create --source-branch release/1.2.0 --target-branch develop \
  --title "chore: sync release/1.2.0 to develop"

Orden de MRs en un release

Los MRs incluidos en un release/* deben ordenarse ascendente por created_at (el más antiguo primero).

glab mr list --target-branch develop --state merged \
  --output json | jq 'sort_by(.created_at)'

Las excepciones al orden (hotfix urgente, dependencia bloqueante, revert) deben quedar justificadas en el MR del release.

Flujo de hotfix

git switch main && git pull origin main
git flow hotfix start 1.2.1
bun commit   # type: fix

git flow publish \
  -o merge_request.create \
  -o merge_request.target=main \
  -o "merge_request.title=fix: critical <description> [1.2.1]"

# Después de que el MR se fusione a main:
git tag -a 1.2.1 -m "Hotfix 1.2.1"
git push origin 1.2.1

# Sync a develop (CRÍTICO — si se omite, el bug vuelve en el siguiente release):
glab mr create --source-branch hotfix/1.2.1 --target-branch develop \
  --title "chore: sync hotfix/1.2.1 to develop"

Template de MR (.gitlab/merge_request_templates/default.md)

## What does this MR do?

## Why is it needed?

## How to test it?

## Checklist
- [ ] Tests passing
- [ ] Self-reviewed
- [ ] Docs updated if needed
- [ ] No critical/high security vulnerabilities