Lista de verificación para la resolución de conflictos de fusión

Un proceso tranquilo y repetible para resolver conflictos de fusión y rebase de Git en repositorios de Python, especialmente pyproject.toml, uv.lock y migraciones de Alembic.

Cómo usar esta lista de verificación

• Sigue los elementos en orden durante un conflicto activo; no saltes directamente a editar marcadores.
• Un archivo completamente resuelto y probado antes de pasar al siguiente cuando los conflictos son grandes.
• Si te quedas atascado en un archivo durante más de 30 minutos, haz una pausa y trabaja en pareja; las migraciones y los archivos de bloqueo se benefician de un segundo revisor.
• Registra la causa del conflicto en la descripción del PR para evitar colisiones repetidas.

Fase 1 - Estabilizar

1. Confirma el tipo de operación: Asegúrate de si estás en merge, rebase o cherry-pick; git status muestra el estado actual.
2. Lista los archivos en conflicto: git diff --name-only --diff-filter=U; espera pyproject.toml, uv.lock, alembic/versions/*.py.
3. Aborta si la rama es incorrecta: git merge --abort o git rebase --abort si comenzaste en una base incorrecta.
4. Guarda el trabajo en progreso no relacionado: git stash push -m "pre-conflict" si las ediciones no confirmadas se mezclan con la resolución de conflictos.
5. Obtén lo último del remoto: git fetch origin para resolver contra la rama main actual, no una copia local obsoleta.

Fase 2 - Comprender

6. Lee ambos lados: Abre el archivo en conflicto; <<<<<<<, =======, >>>>>>> marcan el tuyo frente a la entrada.
7. Verifica los mensajes de confirmación: git log --oneline --left-right HEAD...MERGE_HEAD (para fusión) o las confirmaciones entrantes en rebase.
8. Identifica la intención semántica: ¿Es el conflicto cosmético (orden de importación) o de comportamiento (versión de dependencia, revisión de migración)?
9. Regla del archivo de bloqueo: Para uv.lock / poetry.lock, elige el lado ganador de pyproject.toml, elimina los marcadores de conflicto y ejecuta uv lock.
10. Regla de migración: Para Alembic, nunca dupliques los IDs de revisión; puede que necesites alembic merge heads después de la resolución.

Fase 3 - Resolver

11. Resuelve un archivo a la vez: Elimina todos los marcadores de conflicto; deja sintaxis válida de Python/TOML.
12. Prefiere la política de dependencias del upstream: Cuando no estés seguro sobre la versión de una biblioteca, alinéate con main a menos que el ticket requiera una actualización.
13. Ejecuta el formateador en Python modificado: uv run ruff format en los archivos .py resueltos.
14. Prepara el archivo resuelto: git add <archivo> solo cuando los marcadores se hayan eliminado por completo; git diff --check detecta los que quedan.
15. Continúa la operación: git rebase --continue o completa la confirmación de fusión después de que todos los archivos estén preparados.

Fase 4 - Verificar

16. Sincroniza el entorno: uv sync --frozen debe tener éxito después de la resolución del archivo de bloqueo.
17. Limpia: uv run ruff check .
18. Comprobación de tipos (si está configurado): uv run mypy src/ o pyright en los paquetes afectados.
19. Pruebas: uv run pytest -q; pruebas del módulo afectado como mínimo si la suite completa es lenta.
20. Migraciones: uv run alembic upgrade head en la base de datos local cuando los archivos de migración entraron en conflicto.

Fase 5 - Finalizar

21. Revisa el tamaño del diff: git diff origin/main...HEAD; asegúrate de que no haya eliminaciones accidentales del trabajo de otros.
22. Fuerza el push de forma segura después del rebase: git push --force-with-lease solo en tu rama de características.
23. Comentario en el PR: Anota los archivos en conflicto y cómo elegiste las versiones; esto ayuda a los revisores a centrarse.
24. Prevención de seguimiento: Divide el ticket o haz rebase con más frecuencia si los mismos archivos entran en conflicto repetidamente.
25. Cierra el ciclo con el autor: Si el cambio entrante fue malinterpretado, sincronízate con el autor de la confirmación original antes de fusionar.

Aplicación de la lista de verificación en orden

• Fases 1-2 (1-10): La comprensión antes de editar evita fusiones del lado incorrecto que pasan las pruebas pero rompen las dependencias de producción.
• Fases 3-4 (11-20): Las puertas de verificación detectan archivos de bloqueo que se analizan pero fijan versiones incompatibles.
• Fase 5 (21-25): La comunicación reduce los conflictos repetidos en archivos "calientes" como pyproject.toml.

Preguntas frecuentes

Relacionados

• Ramificación y Fusión - cuándo surgen conflictos
• Comandos Esenciales de Git - comandos de abortar/continuar
• Resolución de Dependencias y Archivos de Bloqueo - política de bloqueo
• Alembic - fusiones de migración

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+.