Git Workflow

Nosso fluxo Git usa um modelo simplificado com duas branches principais e rebase para manter histórico linear.

Visão Geral

gitGraph
    commit id: "Initial setup"
    branch dev
    checkout dev
    commit id: "Dev base"

    branch feature-123
    checkout feature-123
    commit id: "WIP: Feature"
    commit id: "Complete feature"

    checkout dev
    merge feature-123 id: "PR approved" tag: "Deploy staging"
    commit id: "Testing in staging"

    checkout main
    merge dev id: "PR to prod" tag: "Deploy production"

    branch hotfix-critical
    checkout hotfix-critical
    commit id: "Fix critical bug"

    checkout main
    merge hotfix-critical id: "Hotfix PR" tag: "Deploy prod"

    checkout dev
    merge main id: "Sync dev with main"

Branches Principais

`main` - Produção

Propósito: Código em produção
Proteção: Branch protegida, requer PR + review
Deploy: Automático para production após merge
Estabilidade: Sempre deve estar em estado deployable

`dev` - Desenvolvimento/Staging

Propósito: Integração e testes em staging
Proteção: Branch protegida, requer PR + review
Deploy: Automático para staging após merge
Uso: Base para todas as features

Fluxo 1: Feature Development

1. Criar Feature Branch

# Certifique-se de estar em dev atualizada
git checkout dev
git pull origin dev

# Criar branch da feature
git checkout -b feature/ISSUE-123-add-user-authentication

Nomenclatura de branches:

feature/ISSUE-123-description - Nova funcionalidade
fix/ISSUE-456-bug-description - Bug fix
refactor/improve-performance - Refatoração
docs/update-api-docs - Apenas documentação

2. Desenvolver

# Fazer alterações no código
# Adicionar testes
# Atualizar documentação

# Commits frequentes e atômicos
git add .
git commit -m "feat(auth): add JWT token generation

- Implement JWT token service
- Add token expiration logic
- Add tests for token generation

Implements #123"

Convenção de Commits (Conventional Commits):

<type>(<scope>): <subject>

[optional body]

[optional footer]

Types:

feat: Nova funcionalidade
fix: Bug fix
docs: Documentação
style: Formatação (não afeta código)
refactor: Refatoração
test: Adicionar/modificar testes
chore: Manutenção, deps, config

Exemplos:

git commit -m "feat(auth): add JWT validation"
git commit -m "fix(api): handle null response from external service"
git commit -m "docs(readme): update setup instructions"
git commit -m "test(users): add integration tests for user creation"

3. Sincronizar com dev (Rebase)

Antes de abrir PR, sincronize com dev usando rebase:

# Buscar últimas mudanças
git fetch origin

# Rebase sua branch com dev
git rebase origin/dev

# Se houver conflitos:
# 1. Resolver conflitos nos arquivos
# 2. git add <arquivos-resolvidos>
# 3. git rebase --continue
# 4. Repetir até finalizar rebase

Por que rebase?

Histórico linear e limpo
Fácil de entender o que mudou
Bisect mais efetivo
Rollback mais simples

4. Push e Abrir PR

# Push da branch (primeira vez)
git push origin feature/ISSUE-123-add-user-authentication

# Se já fez push antes e fez rebase:
git push origin feature/ISSUE-123-add-user-authentication --force-with-lease

Abrir PR no GitHub:

Acesse repositório no GitHub
Clique em "Compare & pull request"
Base: dev (não main!)
Preencha template do PR:
Título claro
Descrição do que foi feito
Link para issue
Screenshots se aplicável
Checklist de testes
Adicione label apropriada
Marque reviewers
Clique em "Create pull request"

5. Code Review

Aguarde review de ao menos 1 pessoa
Responda comentários
Faça ajustes solicitados
Marque resolve quando resolver comentário
CI deve passar (testes, linter)

Ver guia de Code Review →

6. Merge e Deploy

Após aprovação:

Merge via GitHub (squash ou rebase)
Branch é deletada automaticamente
CI/CD faz deploy automático para staging
Teste sua feature em staging

7. Deploy para Produção

Quando staging estiver testado e aprovado:

# Criar PR de dev para main
git checkout dev
git pull origin dev
git checkout -b release/sprint-X

# Abrir PR de dev → main com:
# - Lista de tudo que está sendo deployado
# - Screenshots/evidências de testes
# - Checklist de deploy

Após merge em main:

Deploy automático para production
Monitorar logs e métricas
Verificar smoke tests

Fluxo 2: Hotfix (Produção)

Para bugs críticos em produção que não podem esperar:

1. Criar Hotfix Branch

# Branch a partir de main
git checkout main
git pull origin main
git checkout -b hotfix/fix-critical-payment-bug

2. Implementar Fix

# Fazer correção mínima necessária
# Adicionar teste que reproduz o bug
# Verificar que fix resolve o problema

git add .
git commit -m "fix(payment): prevent duplicate charge

- Add idempotency check
- Add test for duplicate payment scenario

Fixes #789 (CRITICAL)"

3. PR para main

git push origin hotfix/fix-critical-payment-bug

Abrir PR:

Base: main
Label: hotfix e priority: critical
Marcar como hotfix no título: [HOTFIX] Fix critical payment bug
Explicar impacto e urgência

4. Fast-track Review

Pode ter aprovação acelerada (1 reviewer apenas se crítico)
CI deve passar
Merge assim que aprovado

5. Deploy para Produção

Deploy automático para production
Monitorar intensivamente por 30 minutos
Verificar que bug foi resolvido

6. Sincronizar dev

IMPORTANTE: Após hotfix em main, sincronizar dev:

git checkout dev
git pull origin dev
git rebase origin/main
git push origin dev --force-with-lease

# Isso garante que dev tem o hotfix também

Deploy automático para staging ocorre após push.

Comandos Úteis

Verificar status

# Ver branch atual e mudanças
git status

# Ver diferenças não commitadas
git diff

# Ver histórico de commits
git log --oneline --graph --all

Desfazer mudanças

# Descartar mudanças locais em arquivo
git checkout -- arquivo.py

# Descartar todas as mudanças locais
git reset --hard

# Desfazer último commit (mantém mudanças)
git reset --soft HEAD~1

# Desfazer último commit (descarta mudanças)
git reset --hard HEAD~1

Resolver conflitos

# Durante rebase, se houver conflito:

# 1. Ver arquivos em conflito
git status

# 2. Abrir arquivo e resolver manualmente
# Procure por <<<<<<, ======, >>>>>>

# 3. Marcar como resolvido
git add arquivo-resolvido.py

# 4. Continuar rebase
git rebase --continue

# Se quiser cancelar o rebase:
git rebase --abort

Stash (guardar mudanças temporariamente)

# Guardar mudanças atuais
git stash

# Ver stashes
git stash list

# Recuperar último stash
git stash pop

# Recuperar stash específico
git stash pop stash@{1}

Regras e Boas Práticas

✅ Fazer

✅ Commits atômicos e bem descritos
✅ Rebase antes de abrir PR
✅ Branches de curta duração (máx 2-3 dias)
✅ Testes antes de push
✅ Code review antes de merge
✅ Deletar branch após merge
✅ Usar Conventional Commits

❌ Evitar

❌ Commit diretamente em dev ou main
❌ Push sem rebase antes
❌ Branches de longa duração
❌ Commits com mensagem "wip" ou "fix"
❌ Merge commits (use rebase)
❌ Force push sem --force-with-lease
❌ Commit de secrets ou credenciais

Proteção de Branches

Ambas dev e main têm as seguintes proteções:

✅ Requer PR para qualquer mudança
✅ Requer ao menos 1 aprovação
✅ CI deve passar
✅ Branch deve estar atualizada
✅ Não permite force push direto
✅ Apenas admins podem forçar merge

Troubleshooting

"Cannot push, branch is behind"

# Sua branch está desatualizada
git fetch origin
git rebase origin/dev
git push --force-with-lease

"Cannot rebase, you have unstaged changes"

# Commitar ou stash mudanças primeiro
git stash
git rebase origin/dev
git stash pop

"Merge conflict during rebase"

# 1. Ver conflitos
git status

# 2. Resolver manualmente nos arquivos

# 3. Marcar como resolvido
git add .

# 4. Continuar
git rebase --continue

# Se ficar preso, aborte e peça ajuda
git rebase --abort

"Accidentally committed to main/dev"

# Se não fez push ainda:
git reset --soft HEAD~1  # Desfaz commit mas mantém mudanças
git stash                # Guarda mudanças
git checkout dev         # Vai para branch correta
git checkout -b feature/minha-feature
git stash pop            # Recupera mudanças
git add .
git commit              # Commit novamente

FAQ

P: Por que rebase e não merge?

R: Rebase mantém histórico linear, mais fácil de entender e fazer rollback.

P: Posso fazer force push?

R: Apenas na sua própria branch e com --force-with-lease (mais seguro).

P: E se meu PR tiver conflitos com dev?

R: Faça rebase com dev, resolva conflitos, e push novamente.

P: Quanto tempo deve durar uma feature branch?

R: Ideal: 1-3 dias. Máximo: 1 semana. Se maior, quebre em PRs menores.

P: Posso trabalhar em múltiplas features ao mesmo tempo?

R: Pode, mas use branches separadas. Evite misturar features em um PR.

P: O que fazer se CI falhar?

R: Corrija localmente, commit, push. CI rodará novamente.