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.
//
Busca en todas las páginas de la documentación
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.
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).
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.
IDs de tickets en cada commit: feat(billing): tax line [BILL-42] - los cherry-picks a release/* dependen de mensajes trazables.
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.
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.
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).
La rama de lanzamiento solo acepta correcciones de errores (bugfixes): Aplícalo con protección de rama durante las ventanas de congelación.
Haz cherry-pick a release/*, nunca fusiones main en release/*: Fusionar trae características no verificadas al candidato de lanzamiento.
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.
Fusiona release/* de vuelta a main después del despliegue: Preserva el límite del "tren"; elimina la rama de lanzamiento cuando esté completa.
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.
Haz backport de cada hotfix: Haz cherry-pick del SHA de la corrección a main y abre release/* si aún está activa.
Nunca hagas push forzado de ramas compartidas: El historial de main, release/*, hotfix/* es evidencia de auditoría.
pre-commit replica CI: ruff check, ruff format, pytest rápido - los mismos comandos que GitHub Actions (Configuración de Git).
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.
La protección de ramas requiere verificaciones de estado (status checks): La política supera el sistema de honor para flujos de trabajo requeridos.
Nunca confirmes .env o secretos: Solo .env.example; producción a través de inyección de secretos de plataforma.
No confirmes .venv/, __pycache__/ o dist/: Los artefactos pertenecen a CI/CD, no a git.
Commits convencionales para automatización de changelog: Empareja con semantic-release o un script de changelog personalizado si se adopta.
Creación de etiquetas restringida: Las etiquetas activan la producción - reglas o rol de gestor de lanzamientos.
Monorepo: documenta la estrategia de etiquetas: Una etiqueta de monorepo vs. etiquetas por servicio - elige una y documéntala.
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.
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.
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.
Rebase interactivo solo en feat/* privadas: --force-with-lease antes de la revisión del PR; nunca en ramas compartidas.
La mayoría de los equipos de servicios de Python usan trunk + release/hotfix - más simple que un develop de larga duración a menos que la organización exija GitFlow.
Forzar el ID del ticket y el modo imperativo; tipo y alcance convencionales cuando la automatización del changelog depende de ello.
Fusionar automáticamente los incrementos de parche (patch bumps) cuando CI está en verde; menores/mayores necesitan revisión humana de la diferencia del lockfile.
Sigue Git para Datos/Notebooks - nbstripout obligatorio.
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+.
Revisado por Chris St. John·Última actualización: 16 jul 2026