Coblyn

Español

English

Español

English

Appearance

Coblyn Git Workflow ​

⏱ 6 minNivel · Contribuidorv1.16.0

Estrategia de branching y workflow de desarrollo para Coblyn, con separación clara entre código estable (imaging) y experimental (MDM).

Branch Strategy ​

main                              [PRODUCCIÓN ESTABLE - v1.3.5]
  │                               Sistema PXE funcional
  │                               Despliegue: Clonezilla, WIM, Macrium
  │
  ├─ develop                      [INTEGRACIÓN CONTINUA]
  │   │                           Features estables pre-release
  │   │
  │   ├─ feature/macrium-support  [Feature: Soporte Macrium Reflect]
  │   ├─ feature/enhanced-ui      [Feature: Mejoras UI/UX]
  │   ├─ feature/nfs-optimization [Feature: Optimización NFS]
  │   └─ hotfix/dhcp-lease-bug    [Hotfix: Bug crítico]
  │
  └─ experimental/mdm-foundation  [🧪 EXPERIMENTAL MDM]
      │                           Base para desarrollo MDM
      │                           NO mergeado a main hasta v2.0
      │
      ├─ mdm/autopilot-profiles   [MDM: Provisioning profiles]
      │   └─ unattend-generator   [Sub: Generador unattend.xml]
      │
      ├─ mdm/config-engine        [MDM: Policy engine]
      │   ├─ policy-enforcer      [Sub: Enforcer de políticas]
      │   └─ drift-detection      [Sub: Detección drift]
      │
      ├─ mdm/app-catalog          [MDM: App deployment]
      │   ├─ deployment-engine    [Sub: Motor despliegue]
      │   └─ auto-update          [Sub: Auto-actualización]
      │
      └─ mdm/compliance           [MDM: Compliance & reporting]
          ├─ health-dashboard     [Sub: Dashboard health]
          └─ audit-log            [Sub: Audit trail]

Workflows por Tipo de Cambio ​

1. Feature Estable (Imaging Tradicional) ​

Para: Mejoras a funcionalidades existentes de PXE/imaging que no requieren arquitectura MDM.

bash
# 1. Crear feature branch desde develop
git checkout develop
git pull origin develop
git checkout -b feature/nombre-descriptivo

# 2. Desarrollo
# ... editar código ...
git add .
git commit -m "feat: descripción concisa"

# 3. Testing local
docker compose up -d --build
pytest web/backend/tests/

# 4. Push y Pull Request
git push origin feature/nombre-descriptivo
# Crear PR: feature/nombre-descriptivo → develop

# 5. Después de merge a develop
git checkout develop
git pull origin develop
git branch -d feature/nombre-descriptivo

Merge a main:

  • Cuando develop acumula suficientes features (cada 2-4 semanas)
  • Crear PR: develop → main
  • Tag release: git tag v1.4.0 && git push --tags

2. Feature Experimental MDM ​

Para: Nuevas funcionalidades MDM (provisioning, policies, compliance, etc.).

bash
# 1. Crear MDM feature branch
git checkout experimental/mdm-foundation
git pull origin experimental/mdm-foundation
git checkout -b mdm/nombre-feature

# 2. Desarrollo (seguir convenciones MDM)
# ... editar código en módulos MDM ...
git add web/backend/routers/provisioning.py
git commit -m "feat(mdm): Add provisioning profiles API"

# 3. Testing aislado
docker compose -f docker-compose.mdm.yml up -d --build
pytest web/backend/tests/mdm/

# 4. Push y Pull Request
git push origin mdm/nombre-feature
# Crear PR: mdm/nombre-feature → experimental/mdm-foundation

# 5. Después de merge
git checkout experimental/mdm-foundation
git pull origin experimental/mdm-foundation
git branch -d mdm/nombre-feature

🚨 IMPORTANTE: Features MDM NO se mergean a main hasta:

  • Fase 4 completada (Compliance & Reporting)
  • Testing exhaustivo con beta testers
  • Feature flag implementado para habilitar/deshabilitar MDM
  • Decisión de release v2.0 "Shaft"

3. Hotfix Crítico ​

Para: Bugs críticos en producción que requieren fix inmediato.

bash
# 1. Crear hotfix branch desde main
git checkout main
git pull origin main
git checkout -b hotfix/descripcion-bug

# 2. Fix rápido
# ... corregir bug ...
git add .
git commit -m "fix: descripción del bug corregido"

# 3. Testing acelerado
docker compose up -d --build
# Verificar que el bug está resuelto

# 4. Merge a main Y develop
git checkout main
git merge hotfix/descripcion-bug
git push origin main
git tag v1.3.6  # Incrementar PATCH
git push --tags

git checkout develop
git merge hotfix/descripcion-bug
git push origin develop

# 5. Cleanup
git branch -d hotfix/descripcion-bug

Convenciones de Commits ​

Seguir Conventional Commits (https://www.conventionalcommits.org/):

Formato ​

<tipo>[opcional ámbito]: <descripción>

[opcional cuerpo]

[opcional footer]

Tipos ​

  • feat: Nueva funcionalidad
  • fix: Corrección de bug
  • docs: Cambios solo en documentación
  • style: Cambios de formato (sin afectar lógica)
  • refactor: Refactorización de código
  • perf: Mejoras de rendimiento
  • test: Añadir o corregir tests
  • chore: Cambios en build, herramientas, etc.

Ámbitos (opcional) ​

  • (mdm): Cambios en módulos MDM
  • (pxe): Cambios en cadena PXE
  • (ui): Cambios en frontend
  • (api): Cambios en backend API
  • (docker): Cambios en Docker/compose

Ejemplos ​

bash
# Feature estable
git commit -m "feat(pxe): Add Macrium Reflect boot support"

# Feature MDM
git commit -m "feat(mdm): Implement unattend.xml generator"

# Bugfix
git commit -m "fix(api): Resolve DHCP webhook 500 error on duplicate MAC"

# Documentación
git commit -m "docs: Update PXE chain troubleshooting guide"

# Refactor
git commit -m "refactor(ui): Extract device table to reusable component"

Versionado Semántico ​

Formato: MAJOR.MINOR.PATCH (ej: v1.3.5)

Incrementar MAJOR (v2.0.0) ​

Cuando:

  • Cambios incompatibles con versiones anteriores
  • Reescritura significativa de arquitectura
  • Release de MDM completo (v1.x → v2.0 "Shaft")

Incrementar MINOR (v1.4.0) ​

Cuando:

  • Nueva funcionalidad compatible con versiones anteriores
  • Mejoras significativas a features existentes
  • Acumulación de varias features desde develop

Incrementar PATCH (v1.3.6) ​

Cuando:

  • Hotfix de bugs críticos
  • Correcciones menores sin nueva funcionalidad
  • Actualizaciones de dependencias (seguridad)

Tags ​

bash
# Crear tag anotado
git tag -a v1.4.0 -m "Release v1.4.0: Enhanced UI + NFS optimization"
git push origin v1.4.0

# Listar tags
git tag -l

# Ver detalles de tag
git show v1.4.0

Pull Request Guidelines ​

Template de PR ​

markdown
## Descripción
Breve descripción de los cambios y motivación.

## Tipo de cambio
- [ ] Feature estable (imaging)
- [ ] Feature MDM (experimental)
- [ ] Bugfix
- [ ] Hotfix crítico
- [ ] Documentación

## Testing
- [ ] Tests unitarios pasando (`pytest`)
- [ ] Tests E2E pasando (si aplica)
- [ ] Testeado manualmente con VM de prueba
- [ ] No rompe funcionalidad existente

## Checklist
- [ ] Código sigue convenciones del proyecto
- [ ] Commits siguen Conventional Commits
- [ ] Documentación actualizada (si aplica)
- [ ] Variables de entorno documentadas en `.env.example`
- [ ] Migración de DB incluida (si aplica)

Criterios de Aprobación ​

Para merges a develop:

  • ✅ Tests pasando
  • ✅ Sin conflictos con develop
  • ✅ Code review (opcional si solo tú)
  • ✅ Documentación actualizada

Para merges a main:

  • ✅ Todo lo anterior +
  • ✅ Testeado en entorno staging
  • ✅ Changelog actualizado
  • ✅ Tag de versión creado

Para merges de experimental/mdm-foundation a main:

  • ✅ TODO lo anterior +
  • ✅ Feature flag implementado
  • ✅ Documentación de usuario final
  • ✅ Plan de migración desde v1.x
  • ✅ Beta testing completado
  • ✅ Aprobación explícita del maintainer (tú)

Release Process ​

Minor/Major Release (v1.4.0, v2.0.0) ​

  1. Preparar release branch:

    bash
    git checkout develop
git pull origin develop
git checkout -b release/v1.4.0

  2. Actualizar versiones:

    bash
    # Actualizar version en:
# - web/backend/main.py (FastAPI version)
# - web/frontend/package.json (version)
# - README.md (badges, version mentions)

  3. Generar CHANGELOG:

    bash
    # Usar conventional-changelog o manual
vim CHANGELOG.md

  4. Testing final:

    bash
    docker compose down -v
docker compose up -d --build
# Testing exhaustivo

  5. Merge a main:

    bash
    git checkout main
git merge release/v1.4.0
git tag -a v1.4.0 -m "Release v1.4.0: Features X, Y, Z"
git push origin main
git push --tags

  6. Merge back a develop:

    bash
    git checkout develop
git merge main
git push origin develop

  7. Cleanup:

    bash
    git branch -d release/v1.4.0

Patch Release (v1.3.6) ​

Proceso simplificado para hotfixes:

bash
# Desde hotfix branch
git checkout main
git merge hotfix/nombre
git tag v1.3.6
git push origin main --tags

git checkout develop
git merge hotfix/nombre
git push origin develop

Protección de Branches ​

Configurar en GitHub/GitLab:

main ​

  • ✅ Require pull request before merging
  • ✅ Require status checks to pass
  • ✅ Require branches to be up to date
  • ✅ Require linear history (opcional)
  • ❌ Allow force pushes

develop ​

  • ✅ Require pull request before merging
  • ❌ Allow force pushes

experimental/mdm-foundation ​

  • ⚠️ Requiere PR pero permite force push (es experimental)

Ejemplo de Historial Git ​

* e4f8c2a (HEAD -> main, tag: v1.3.5) Release v1.3.5: Macrium support
*   d3b7a1c Merge pull request #42 from feature/macrium-support
|\
| * c2a6f9e feat: Add Macrium Reflect iPXE boot entry
| * b1e5d8e test: Add Macrium boot chain tests
|/
* a0c4e7d (tag: v1.3.4) Release v1.3.4: NFS optimization
*   9f3b6c5 Merge pull request #40 from feature/nfs-optimization
|\
| * 8e2a5b4 perf(nfs): Optimize mount options for large images
|/
* 7d1c4a3 fix: Resolve DHCP lease conflict on ProxyDHCP mode
* 6c0b3a2 (tag: v1.3.3) Release v1.3.3: Enhanced UI

... (historial continúa)

Paralelo en rama experimental:

* f5e9d3b (HEAD -> experimental/mdm-foundation) Merge mdm/autopilot-profiles
|\
| * e4d8c2b feat(mdm): Add provisioning profiles API
| * d3c7b1a feat(mdm): Implement unattend.xml generator
|/
* c2b6a0d feat(mdm): Initial MDM foundation setup
* b1a5e9d (tag: v1.3.5) Branch experimental/mdm-foundation from main v1.3.5

Comandos Útiles ​

Ver diferencias entre branches ​

bash
# Ver qué hay en develop que no está en main
git log main..develop --oneline

# Ver archivos modificados entre branches
git diff --name-status main..develop

Limpiar branches locales obsoletas ​

bash
# Ver branches mergeadas
git branch --merged main

# Eliminar branches mergeadas (excepto main/develop)
git branch --merged main | grep -v "^\*\|main\|develop" | xargs git branch -d

Ver historial de un archivo ​

bash
git log --follow -- web/backend/main.py

Revertir un commit problemático ​

bash
# Crear commit que deshace cambios de otro commit
git revert <commit-hash>
git push origin <branch>

Cherry-pick un commit específico ​

bash
# Aplicar commit de una rama a otra
git checkout target-branch
git cherry-pick <commit-hash>
git push origin target-branch

Referencias ​

Última actualización: 2026-02-15 Versión del documento: 1.0.0

Coblyn · documentación, demo aislada y canal de instalación separados

© 2026 Coblyn Systems