Guia: Gerenciamento de Branches e Submódulos Git

📚 Conceitos Fundamentais

Como Funcionam Git Submodules

Um submódulo Git é um repositório Git dentro de outro repositório Git. O repositório principal armazena: - O caminho do submódulo - O commit específico que o submódulo deve usar - O branch (opcional, mas recomendado)

Importante: O repositório principal não armazena o código do submódulo, apenas uma referência a um commit específico.

Estrutura de Branches com Submódulos

Repositório Principal (ds-ecosif-ia-services)
├── branch: develop
│   ├── ecosif-compliance → commit ABC123 (branch: develop)
│   ├── ecosif-structure → commit DEF456 (branch: develop)
│   └── ecosif-angular → commit GHI789 (branch: develop)
│
├── branch: qas
│   ├── ecosif-compliance → commit ABC999 (branch: develop ou qas)
│   ├── ecosif-structure → commit DEF888 (branch: develop ou qas)
│   └── ecosif-angular → commit GHI777 (branch: develop ou qas)
│
└── branch: production
    ├── ecosif-compliance → commit ABC000 (branch: production ou tag v1.0.0)
    ├── ecosif-structure → commit DEF111 (branch: production ou tag v1.0.0)
    └── ecosif-angular → commit GHI222 (branch: production ou tag v1.0.0)

Regra de Ouro: Cada branch do repositório principal deve apontar para commits compatíveis dos submódulos.

🎯 Passo 1: Merge do feature/java17-migration para develop

1.1 Preparação

# 1. Garantir que está no branch correto
cd /opt/ds-ecosif-ia-services
git checkout feature/java17-migration
git pull origin feature/java17-migration

# 2. Verificar status dos submódulos
git submodule status

# 3. Atualizar submódulos para os commits corretos
git submodule update --init --recursive

1.2 Merge no Repositório Principal

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

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

- Migração para Java 17
- Atualizações de dependências
- Correções de compliance e estrutura"

# 3. Resolver conflitos se houver
# (se houver conflitos, resolva e faça git add . && git commit)

# 4. Verificar status
git status
git log --oneline -5

1.3 Ajustar Submódulos para Apontar para develop

IMPORTANTE: Após o merge, os submódulos ainda apontam para commits do feature/java17-migration. Precisamos atualizá-los para apontar para o branch develop de cada submódulo.

# Para cada submódulo, fazer:

# 1. Entrar no submódulo
cd ecosif-compliance
git checkout develop
git pull origin develop

# 2. Voltar ao repositório principal
cd ..

# 3. Adicionar a atualização do submódulo
git add ecosif-compliance
git commit -m "chore: atualizar ecosif-compliance para branch develop"

# Repetir para cada submódulo:
cd ecosif-structure && git checkout develop && git pull origin develop && cd .. && git add ecosif-structure && git commit -m "chore: atualizar ecosif-structure para branch develop"
cd ecosif-angular && git checkout develop && git pull origin develop && cd .. && git add ecosif-angular && git commit -m "chore: atualizar ecosif-angular para branch develop"
# ... e assim por diante para todos os submódulos

1.4 Push para Remote

# Push do develop atualizado
git push origin develop

# Se os submódulos também precisarem de push:
cd ecosif-compliance && git push origin develop && cd ..
cd ecosif-structure && git push origin develop && cd ..
# ... etc

🔧 Passo 2: Configurar Submódulos para Usar Branch develop

2.1 Configurar Branch Padrão dos Submódulos

Por padrão, submódulos ficam em estado "detached HEAD". Para que sempre sigam um branch:

# No repositório principal, configurar cada submódulo:

# 1. Entrar no submódulo
cd ecosif-compliance

# 2. Verificar branch atual
git branch -a

# 3. Mudar para develop e configurar tracking
git checkout develop
git branch --set-upstream-to=origin/develop develop

# 4. Voltar ao repositório principal
cd ..

# 5. Configurar o submódulo para seguir o branch develop
git config -f .gitmodules submodule.ecosif-compliance.branch develop

# Repetir para todos os submódulos:
git config -f .gitmodules submodule.ecosif-structure.branch develop
git config -f .gitmodules submodule.ecosif-angular.branch develop
# ... etc

# 6. Commitar a mudança no .gitmodules
git add .gitmodules
git commit -m "chore: configurar submódulos para seguir branch develop"

2.2 Verificar Configuração

# Ver configuração dos submódulos
cat .gitmodules

# Deve mostrar algo como:
# [submodule "ecosif-compliance"]
#   path = ecosif-compliance
#   url = <url-do-repositorio>
#   branch = develop

🏗️ Passo 3: Criar Processo de Versionamento por Ambiente

3.1 Estrutura de Branches Recomendada

┌─────────────────────────────────────────────────────────┐
│  REPOSITÓRIO PRINCIPAL (ds-ecosif-ia-services)         │
├─────────────────────────────────────────────────────────┤
│  develop  → Submódulos apontam para branch develop      │
│  qas      → Submódulos apontam para branch develop/qas  │
│  production → Submódulos apontam para tags/commits fixos│
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│  CADA SUBMÓDULO (ecosif-*, etc)                         │
├─────────────────────────────────────────────────────────┤
│  develop  → Desenvolvimento ativo                        │
│  qas      → Versão para QA (opcional, pode usar develop)│
│  production → Versão estável (ou usar tags)              │
└─────────────────────────────────────────────────────────┘

3.2 Script de Atualização de Ambiente

Crie um script scripts/sync-submodules.sh:

#!/bin/bash
# scripts/sync-submodules.sh
# Sincroniza submódulos com o branch especificado

BRANCH=${1:-develop}
ENVIRONMENT=${2:-develop}

echo "🔄 Sincronizando submódulos para branch: $BRANCH (ambiente: $ENVIRONMENT)"

# Lista de submódulos
SUBMODULES=(
    "ecosif-compliance"
    "ecosif-structure"
    "ecosif-angular"
    "ecosif-auth"
    "ecosif-masterdata"
    "ecosif-moviments"
    "ecosif-querys"
    "ecosif-reports"
    # Adicione outros conforme necessário
)

for submodule in "${SUBMODULES[@]}"; do
    echo ""
    echo "📦 Processando: $submodule"

    if [ ! -d "$submodule" ]; then
        echo "  ⚠️  Diretório não encontrado, pulando..."
        continue
    fi

    cd "$submodule"

    # Verificar se é um repositório git válido
    if [ ! -d ".git" ]; then
        echo "  ⚠️  Não é um repositório git, pulando..."
        cd ..
        continue
    fi

    # Mudar para o branch especificado
    echo "  🔀 Mudando para branch: $BRANCH"
    git fetch origin
    git checkout "$BRANCH" 2>/dev/null || git checkout -b "$BRANCH" "origin/$BRANCH"
    git pull origin "$BRANCH"

    # Mostrar commit atual
    CURRENT_COMMIT=$(git rev-parse --short HEAD)
    CURRENT_BRANCH=$(git branch --show-current)
    echo "  ✅ Commit atual: $CURRENT_COMMIT (branch: $CURRENT_BRANCH)"

    cd ..
done

echo ""
echo "✅ Sincronização concluída!"
echo ""
echo "📝 Próximos passos:"
echo "   1. Verifique as mudanças: git status"
echo "   2. Adicione os submódulos atualizados: git add <submodule>"
echo "   3. Faça commit: git commit -m 'chore: atualizar submódulos para $ENVIRONMENT'"

Tornar executável:

chmod +x scripts/sync-submodules.sh

3.3 Workflow por Ambiente

Ambiente: DEVELOP

# 1. Mudar para branch develop
git checkout develop
git pull origin develop

# 2. Sincronizar submódulos para develop
./scripts/sync-submodules.sh develop develop

# 3. Verificar e commitar
git status
git add .
git commit -m "chore: atualizar submódulos para develop"
git push origin develop

Ambiente: QAS

# Opção 1: QAS usa o mesmo branch develop dos submódulos
git checkout qas
git pull origin qas

# Atualizar submódulos para develop (ou qas se existir)
./scripts/sync-submodules.sh develop qas

# Ou Opção 2: QAS tem branch próprio nos submódulos
./scripts/sync-submodules.sh qas qas

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

Ambiente: PRODUCTION

# Production deve usar tags ou commits fixos
git checkout production
git pull origin production

# Opção 1: Usar tags (recomendado)
cd ecosif-compliance
git fetch --tags
git checkout v1.0.0  # ou a tag desejada
cd ..
git add ecosif-compliance

# Repetir para todos os submódulos...

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

# Commitar
git add .
git commit -m "chore: atualizar submódulos para production (v1.0.0)"
git push origin production

📋 Checklist de Migração Completa

Status hub eCosif: migração Java 17 / develop concluída. Itens de treinamento/backup operacional permanecem sob responsabilidade da equipe.

Fase 1: Preparação

• [x] Backup de todos os repositórios
• [x] Verificar que todos os submódulos têm branch develop
• [x] Verificar que o branch feature/java17-migration está atualizado

Fase 2: Merge

• [x] Fazer merge de feature/java17-migration → develop no repositório principal
• [x] Resolver conflitos se houver
• [x] Atualizar cada submódulo para apontar para seu branch develop
• [x] Commitar atualizações dos submódulos
• [x] Push do develop atualizado

Fase 3: Configuração

• [x] Configurar .gitmodules para cada submódulo seguir branch develop
• [x] Criar script sync-submodules.sh
• [x] Testar script em ambiente de desenvolvimento
• [x] Documentar processo

Fase 4: Estabelecer Processo

• [x] Definir estratégia para QAS (develop ou branch próprio) — branch qas
• [x] Definir estratégia para Production (tags ou branch fixo) — master + tags v*
• [x] Criar documentação do processo
• [ ] Treinar equipe

🔍 Comandos Úteis

Verificar Status dos Submódulos

# Status detalhado
git submodule status

# Ver branch de cada submódulo
git submodule foreach 'echo "$name: $(git branch --show-current)"'

# Ver commits de cada submódulo
git submodule foreach 'echo "$name: $(git rev-parse --short HEAD)"'

Atualizar Todos os Submódulos

# Atualizar para commits referenciados
git submodule update --init --recursive

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

Ver Diferenças nos Submódulos

# Ver o que mudou nos submódulos
git diff --submodule

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

⚠️ Armadilhas Comuns

1. Submódulo em "Detached HEAD"

Problema: Submódulo não está em nenhum branch.

Solução:

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

2. Submódulo Desatualizado

Problema: Submódulo aponta para commit antigo.

Solução:

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

3. Conflitos em Submódulos

Problema: Dois branches apontam para commits diferentes do mesmo submódulo.

Solução: Decidir qual commit usar e atualizar manualmente:

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

📚 Boas Práticas

1. Sempre commitar atualizações de submódulos explicitamente - Não deixe submódulos desatualizados sem commit

2. Usar tags para Production - Tags são imutáveis e facilitam rastreamento

3. Documentar versões compatíveis - Manter um arquivo VERSIONS.md listando versões testadas juntas

4. Automizar quando possível - Scripts reduzem erros humanos

5. Testar em QAS antes de Production - Garantir compatibilidade entre submódulos

🎯 Resumo da Sua Dúvida

Pergunta: "No repositório principal, os submódulos usam feature/java17-migration, mas no develop deveriam usar develop de cada módulo?"

Resposta: SIM, exatamente!

• Branch feature/java17-migration do repositório principal → Submódulos apontam para commits do feature/java17-migration de cada submódulo
• Branch develop do repositório principal → Submódulos devem apontar para commits do develop de cada submódulo
• Branch qas do repositório principal → Submódulos apontam para commits compatíveis (pode ser develop ou qas)
• Branch production do repositório principal → Submódulos apontam para tags ou commits fixos

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