Desarrollar sistemas de visión por computadora con capacidad de detección en tiempo real —como los que identifican el uso correcto de mascarillas— exige coordinación precisa entre múltiples especialistas: investigadores de modelos, ingenieros de inferencia y desarrolladores de interfaces. Sin un flujo de control de versiones riguroso, surgen rápidamente problemas como mezclas no intencionadas de experimentos de entrenamiento, incompatibilidades entre versiones de modelos y bloqueos en integraciones continuas.

Estructura modular y primeros pasos con Git

Antes de inicializar el repositorio, se recomienda adoptar una arquitectura clara que aísle responsabilidades:

mask-rt-project/
├── assets/          # Recursos estáticos (iconos, ejemplos de video)
├── models/          # Modelos exportados (sin pesos binarios en Git)
├── core/            # Lógica central
│   ├── inference/   # Inferencia optimizada (ONNX/Triton)
│   ├── pipeline/    # Flujo de procesamiento de video
│   └── calibration/ # Ajuste de umbrales y métricas
├── ui/              # Interfaz gráfica o API REST
├── scripts/         # Herramientas de evaluación y conversión
├── configs/         # Archivos YAML para hiperparámetros
├── tests/           # Pruebas unitarias y de regresión visual
└── pyproject.toml # Gestión moderna de dependencias

Tras crear la carpeta, se inicializa el repositorio con filtros inteligantes:

mkdir mask-rt-project && cd mask-rt-project
git init

# Generar .gitignore personalizado
cat > .gitignore << 'EOF'
# Binarios y artefactos
*.onnx
*.pt
*.safetensors
models/checkpoints/
models/exported/

# Entornos
.venv/
.env.local
__pycache__/
*.pyc

# Logs y cachés
logs/
*.log
*.csv.tmp

# IDE
.vscode/
.idea/
*.swp

# Sistemas
.DS_Store
Thumbs.db
EOF

git add . && git commit -m "🌱 Estructura inicial con exclusión estratégica"

Estrategia de ramificación centrada en entregables

En lugar de seguir modelos genéricos como Git Flow, se prioriza una estrategia ligera basada en entregables verificables:

• main: Código listo para producción (CI pasa todas las pruebas de precisión y latencia)
• integrate: Ramificación de integración continua (donde confluyen cambios probados)
• task/xxx: Ramas cortas (short-lived) vinculadas a tareas específicas (ej. task/optimize-cpu-latency)
• exp/xxx: Ramas experimentales para investigación (no se fusionan directamente; se documentan resultados)

Ejemplo práctico de creación y fusión segura:

# Partir desde la rama estable más reciente
git checkout integrate
git pull origin integrate

# Crear rama específica para mejora de FPS
git checkout -b task/increase-fps-25

# Después de validación local:
git add core/pipeline/ && git commit -m "perf(pipeline): acelerar preprocesamiento con NumPy vectorizado"

# Fusión con verificación automática
git checkout integrate
git merge --no-ff --no-edit task/increase-fps-25
git push origin integrate
git branch -d task/increase-fps-25

Convenciones de commits orientadas a trazabilidad

Cada mensaje debe permitir reconstruir contexto sin abrir código. Se usa un formato inspirado en Conventional Commits, adaptado al dominio:

<tipo>(<submódulo>): <imperativo en minúscula>

- Cambios observables (métricas, tiempo de respuesta)
- Referencia a benchmark usado (ej. "evaluado en COCO-Mask v0.2")
- Si aplica: ID de experimento en MLflow o Weights & Biases

Ejemplos válidos:

fix(inference): corregir desbordamiento de buffer en streams RTSP

- Resuelve caída al procesar flujos >30 fps
- Validado con test_stream_stress.py (1200 frames)

feat(ui): añadir modo de depuración con heatmap de confianza

- Visualización en tiempo real mediante OpenCV overlay
- Habilitado con flag --debug-heatmap

Automatización con ganchos y CI/CD

Se configuran comprobaciones pre-commit para evitar errores recurrentes:

#!/usr/bin/env bash
# .git/hooks/pre-commit

set -e

echo "🔍 Verificando integridad del pipeline..."
python -m core.pipeline.validate --config configs/default.yaml

echo "🧪 Ejecutando pruebas críticas..."
pytest tests/test_inference.py -x --tb=short -q

echo "🧹 Limpiando archivos temporales..."
find . -name "*.tmp" -delete 2>/dev/null || true

En el pipeline de CI (ej. GitHub Actions), se ejecutan validaciones adicionales:

• Comparación de métricas contra baseline (mAP, FPS, memoria GPU)
• Verificación de compatibilidad de formatos de modelo (ONNX opset, TorchScript)
• Análisis estático con pyright y bandit

Manejo eficiente de activos grandes

Los modelos entrenados se excluyen del control de versiones tradicional. En su lugar:

• Se usa Git LFS solo para checkpoints intermedios necesarios para reproducción
• Modelos finales se publican en un artifact registry (ej. Hugging Face Hub o un bucket S3 privado)
• El repositorio contiene solo model_registry.json con hashes y metadatos

git lfs install
git lfs track "models/checkpoints/*.pth"
git lfs track "assets/videos/*.mp4"
git add .gitattributes

Mantenimiento proactivo del repositorio

Para evitar acumulación de ramas obsoletas, se implementa limpieza semanal automatizada:

# Script de mantenimiento (ejecutar cada lunes)
git fetch --prune
git branch --format='%(refname:short)' --merged integrate | \
  grep -E '^(task|exp)/' | \
  grep -v "$(git rev-parse --abbrev-ref HEAD)" | \
  xargs -r git branch -d

# Reportar ramas remotas huérfanas
git ls-remote --heads origin | cut -f2 | \
  grep -E '^(task|exp)/' | \
  while read b; do
    [[ -z "$(git branch -r | grep "$b")" ]] && echo "⚠️  $b sin tracking local"
  done