Mejores prácticas de Git

Un resumen condensado de las 25 prácticas de Git más importantes para equipos de Python: historial limpio, commits revisables y hooks alineados con CI.

1. main es siempre la verdad de integración: Cada PR fusionado pasa ruff, pytest y typecheck; nunca dejes main roto durante la noche (Comandos Esenciales de Git).

2. Confirma el archivo de bloqueo (lockfile): uv.lock (o poetry.lock) es necesario para uv sync --frozen reproducible en CI; nunca lo ignores en .gitignore.

3. IDs de tickets en cada commit: feat(billing): tax line [BILL-42] - los cherry-picks a release/* dependen de mensajes trazables.

4. Fusiona (squash merge) las características a main: Un ticket, un commit en la rama de integración cuando la política del equipo lo permite.

5. Ramas de características de corta duración: Objetivo de 1-3 días; haz rebase de main diariamente para evitar conflictos de lockfile y Alembic.

6. Crea release/x.y para "trenes" coordinados: API + worker + migración se envían juntos; las nuevas características aterrizan en main hasta la etiqueta (tag).

7. La rama de lanzamiento solo acepta correcciones de errores (bugfixes): Aplícalo con protección de rama durante las ventanas de congelación.

8. Haz cherry-pick a release/*, nunca fusiones main en release/*: Fusionar trae características no verificadas al candidato de lanzamiento.

9. Etiqueta (tag) desde release/* después de la aprobación en staging: v2.6.0 activa el pipeline de lanzamiento; el mensaje de la etiqueta lista los desplegables.

10. Fusiona release/* de vuelta a main después del despliegue: Preserva el límite del "tren"; elimina la rama de lanzamiento cuando esté completa.

11. Ramas de hotfix desde etiquetas de producción: git checkout -b hotfix/2.5.1 v2.5.0 - no desde main cuando esta está adelantada a producción.

12. Haz backport de cada hotfix: Haz cherry-pick del SHA de la corrección a main y abre release/* si aún está activa.

13. Nunca hagas push forzado de ramas compartidas: El historial de main, release/*, hotfix/* es evidencia de auditoría.

14. pre-commit replica CI: ruff check, ruff format, pytest rápido - los mismos comandos que GitHub Actions (Configuración de Git).

15. La plantilla de PR requiere nota de migración: Las revisiones de Alembic necesitan un plan de reversión o una estrategia de expansión-contracción.

16. La protección de ramas requiere verificaciones de estado (status checks): La política supera el sistema de honor para flujos de trabajo requeridos.

17. Nunca confirmes .env o secretos: Solo .env.example; producción a través de inyección de secretos de plataforma.

18. No confirmes .venv/, __pycache__/ o dist/: Los artefactos pertenecen a CI/CD, no a git.

19. Commits convencionales para automatización de changelog: Empareja con semantic-release o un script de changelog personalizado si se adopta.

20. Creación de etiquetas restringida: Las etiquetas activan la producción - reglas o rol de gestor de lanzamientos.

21. Monorepo: documenta la estrategia de etiquetas: Una etiqueta de monorepo vs. etiquetas por servicio - elige una y documéntala.

22. Cambios de esquema de API + worker vinculados: La deriva del contrato de eventos rompe los flujos asíncronos - un PR o PRs explícitamente vinculados.

23. Revisa las diferencias del lockfile en los PR de dependencias: Las nuevas dependencias transitivas inesperadas son señales de alerta de la cadena de suministro.

24. Documenta la reversión en las notas de lanzamiento: Resúmenes de imágenes (image digests), plan de reversión de migración, interruptor de apagado (kill switch) de feature flag.

25. Rebase interactivo solo en feat/* privadas: --force-with-lease antes de la revisión del PR; nunca en ramas compartidas.

Preguntas Frecuentes

Relacionado

• Estrategias de Ramificación y Fusión
• Lista de Verificación de Resolución de Conflictos de Fusión
• CLI de GitHub - automatización de PR
• Pipelines de CI/CD - puertas de flujo de trabajo

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