Resumo Executivo: Gerenciamento de Submódulos Git

Como Funciona na Prática

┌─────────────────────────────────────────────────────────────┐
│ REPOSITÓRIO PRINCIPAL: ds-ecosif-ia-services                 │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│ Branch: feature/java17-migration                             │
│   ├─ ecosif-compliance → commit XYZ (branch: feature/...)   │
│   ├─ ecosif-structure → commit ABC (branch: feature/...)    │
│   └─ ecosif-angular → commit DEF (branch: feature/...)      │
│                                                              │
│ Branch: develop  ← VOCÊ ESTÁ AQUI                            │
│   ├─ ecosif-compliance → commit 123 (branch: develop) ✅    │
│   ├─ ecosif-structure → commit 456 (branch: develop) ✅     │
│   └─ ecosif-angular → commit 789 (branch: develop) ✅        │
│                                                              │
│ Branch: qas                                                  │
│   ├─ ecosif-compliance → commit 999 (branch: develop/qas)  │
│   ├─ ecosif-structure → commit 888 (branch: develop/qas)    │
│   └─ ecosif-angular → commit 777 (branch: develop/qas)       │
│                                                              │
│ Branch: production                                           │
│   ├─ ecosif-compliance → tag v1.0.0 ou commit fixo          │
│   ├─ ecosif-structure → tag v1.0.0 ou commit fixo           │
│   └─ ecosif-angular → tag v1.0.0 ou commit fixo              │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Cada branch do repositório principal "trava" os submódulos em versões específicas e compatíveis.

📋 Passo a Passo Simplificado

1️⃣ Merge feature/java17-migration → develop

# No repositório principal
cd /opt/ds-ecosif-ia-services

# 1. Ir para develop
git checkout develop
git pull origin develop

# 2. Fazer merge
git merge feature/java17-migration --no-ff -m "Merge feature/java17-migration into develop"

# 3. Resolver conflitos se houver
# (editar arquivos, depois: git add . && git commit)

2️⃣ Atualizar Submódulos para develop

# Opção A: Manual (um por um)
cd ecosif-compliance
git checkout develop
git pull origin develop
cd ..
git add ecosif-compliance
git commit -m "chore: atualizar ecosif-compliance para develop"

# Repetir para cada submódulo...

# Opção B: Usar o script (RECOMENDADO)
./scripts/sync-submodules.sh develop develop
git add .
git commit -m "chore: atualizar todos os submódulos para develop"

3️⃣ Configurar Submódulos para Seguir Branch develop

# Configurar cada submódulo para seguir develop automaticamente
git config -f .gitmodules submodule.ecosif-compliance.branch develop
git config -f .gitmodules submodule.ecosif-structure.branch develop
git config -f .gitmodules submodule.ecosif-angular.branch develop
# ... para todos os submódulos

# Commitar a configuração
git add .gitmodules
git commit -m "chore: configurar submódulos para seguir branch develop"

4️⃣ Push

# Push do repositório principal
git push origin develop

# Se os submódulos também precisarem de push (geralmente não necessário)
# cd ecosif-compliance && git push origin develop && cd ..

🔄 Processo Contínuo por Ambiente

Desenvolvimento (develop)

# Sempre que atualizar código nos submódulos
cd ecosif-compliance
# ... fazer alterações ...
git add .
git commit -m "feat: nova funcionalidade"
git push origin develop
cd ..

# No repositório principal, atualizar referência
git submodule update --remote ecosif-compliance
git add ecosif-compliance
git commit -m "chore: atualizar ecosif-compliance"
git push origin develop

QA/Testes (qas)

# Quando develop estiver estável, criar/atualizar qas
git checkout qas
git pull origin qas

# Sincronizar submódulos (pode usar develop ou branch qas próprio)
./scripts/sync-submodules.sh develop qas
# ou
./scripts/sync-submodules.sh qas qas

git add .
git commit -m "chore: atualizar submódulos para QAS"
git push origin qas

Produção (production)

# Quando qas estiver validado, criar release
git checkout production
git pull origin production

# Opção 1: Usar tags (RECOMENDADO)
cd ecosif-compliance
git fetch --tags
git checkout v1.0.0
cd ..
git add ecosif-compliance
# Repetir para todos...

# Opção 2: Usar branch production
./scripts/sync-submodules.sh production production

git add .
git commit -m "chore: release v1.0.0 - atualizar submódulos para production"
git push origin production

🛠️ Comandos Úteis do Dia a Dia

Ver Status dos Submódulos

# Ver branch e commit de cada submódulo
git submodule foreach 'echo "$name: $(git branch --show-current) @ $(git rev-parse --short HEAD)"'

Atualizar Todos os Submódulos

# Atualizar para último commit do branch configurado
git submodule update --remote --recursive

Ver o Que Mudou nos Submódulos

# Ver diferenças
git diff --submodule

# Ver commits novos
git submodule foreach 'git log --oneline origin/develop..HEAD'

Sincronizar Manualmente um Submódulo

cd ecosif-compliance
git checkout develop
git pull origin develop
cd ..
git add ecosif-compliance
git commit -m "chore: atualizar ecosif-compliance"

⚠️ Problemas Comuns e Soluções

Problema 1: Submódulo em "detached HEAD"

cd <submodule>
git checkout develop
git branch --set-upstream-to=origin/develop develop
cd ..

Problema 2: Submódulo desatualizado

git submodule update --remote <submodule>
cd <submodule>
git pull origin develop
cd ..
git add <submodule>
git commit -m "chore: atualizar <submodule>"

Problema 3: Conflito entre branches

# Decidir qual commit usar
cd <submodule>
git checkout <commit-desejado>
cd ..
git add <submodule>
git commit -m "fix: resolver conflito em <submodule>"

📊 Estrutura de Versionamento Recomendada

┌─────────────────────────────────────────────────────────┐
│ DESENVOLVIMENTO                                         │
├─────────────────────────────────────────────────────────┤
│ Repositório Principal: branch develop                    │
│   └─ Submódulos: branch develop (sempre atualizado)     │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│ QA/TESTES                                               │
├─────────────────────────────────────────────────────────┤
│ Repositório Principal: branch qas                        │
│   └─ Submódulos: branch develop (versão estável)         │
│      ou branch qas (se existir)                          │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│ PRODUÇÃO                                                │
├─────────────────────────────────────────────────────────┤
│ Repositório Principal: branch production                 │
│   └─ Submódulos: tags (v1.0.0, v1.1.0, etc)             │
│      ou commits fixos (não mudam sem release)           │
└─────────────────────────────────────────────────────────┘

✅ Checklist de Migração

Status hub eCosif: concluído (branches develop em .gitmodules + scripts de sync).

• [x] Fazer merge feature/java17-migration → develop
• [x] Atualizar cada submódulo para branch develop
• [x] Configurar .gitmodules para seguir develop
• [x] Testar que tudo funciona
• [x] Push do develop atualizado
• [x] Criar/atualizar branch qas se necessário
• [x] Documentar processo para equipe (scripts/sync-submodules.sh, guias em docs/dev/)

🎓 Conceito Chave

Git Submodules armazena apenas referências a commits específicos, não o código.

Quando você muda de branch no repositório principal: - Os submódulos não mudam automaticamente - Você precisa explicitamente atualizar cada submódulo - Cada branch do repositório principal "trava" os submódulos em versões específicas

Isso permite ter versões diferentes e compatíveis dos submódulos em cada ambiente (develop, qas, production).