Ramificación y Fusión

Estrategias de ramas de características, fusión y rebase para servicios de Python que envían pyproject.toml, lockfiles y migraciones de Alembic juntos.

Receta

git checkout main && git pull --rebase origin main
git checkout -b feat/api-91-refunds
# trabajar ...
git fetch origin && git rebase origin/main
git push -u origin feat/api-91-refunds
# abrir PR -> fusionar con squash a main después de que CI esté en verde

Cuándo usar esto:

• Comenzar trabajo de tickets aislado de main
• Integrar el último main antes de la revisión de PR
• Crear líneas de lanzamiento release/x.y con aplicaciones Django/FastAPI
• Backportear hotfixes con cherry-pick

Ejemplo de Trabajo

# Ciclo de vida de la rama de características
git switch -c feat/worker-retries main
uv run pytest -q
git commit -am "feat(worker): retry smtp errors [WRK-12]"
git fetch origin
git rebase origin/main
# conflicto en uv.lock -> regenerar lock después de resolver pyproject
uv lock
git add pyproject.toml uv.lock
git rebase --continue
git push --force-with-lease origin feat/worker-retries

Lo que esto demuestra:

• Ramificación desde main actualizado
• Rebase integra upstream sin commits de fusión en la rama de características
• Conflictos de lockfile resueltos por regeneración, no edición manual
• Force push seguro con --force-with-lease después de rebase

Profundización

Cómo Funciona

• Fast-forward - El puntero de la rama se mueve cuando no hay commits divergentes.
• Commit de fusión - Combina dos historiales con un nodo de fusión.
• Rebase - Reproduce commits sobre una base nueva - reescribe SHAs.
• Fusión con squash - El PR se convierte en un solo commit en main.

Tipos de Ramas

Notas de Python

# Hacer cherry-pick de corrección de migración a la rama de lanzamiento
git switch release/2.3
git cherry-pick abc1234  # commit con revisión de Alembic
uv run alembic upgrade head
uv run pytest -q

Errores Comunes

• Ramas de características de larga duración - Los conflictos de lockfile y migraciones explotan. Solución: fusionar o rebasar main diariamente.
• Squash pierde información de revertir - Difícil de bisectar. Solución: un título de PR significativo se convierte en el mensaje de squash.
• Rebase después de que comienza la revisión del PR - Confunde a los revisores con force push. Solución: comunicar o fusionar en su lugar.
• Fusionar main en release/* - Introduce características no verificadas. Solución: solo cherry-pick.
• Conflictos de revisiones de Alembic - Cabezas duplicadas después de ramas paralelas. Solución: fusionar la migración de cabezas antes del despliegue.
• Conflictos de ruedas binarias - Raros en git; los artefactos grandes no deben estar en el repositorio. Solución: Git LFS o índice de paquetes.

Alternativas

Preguntas Frecuentes

Relacionado

• Comandos Esenciales de Git - comandos diarios
• Lista de Verificación para Resolución de Conflictos de Fusión - proceso calmado
• Worktrees de Git - checkouts paralelos
• Pipelines de CI/CD - protecciones de rama

Versiones de la Pila: Esta página fue escrita para Python 3.14.0 (estable 3.14, mantenimiento 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, y uv 0.6+.