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 mesclar o código
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 mesclar o código
Uso: Base para todas as features

Fluxo 1: Feature Development

1. Criar Feature Apartir da Branch de Dev

# 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
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
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 "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

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 CodeCommit da Aws:

Acesse repositório no CodeCommit
Clique em "Pull requests"
Clique em Create pull request
selecione o source(Sua branch criada para desenvolver) para o Destination(dev) e clique em compare.
Preencha template do PR:
Título claro
Descrição do que foi feito
Clique em "Create pull request"

5. Code Review

Aguarde o Code Review Ver guia de Code Review →)

6. Merge e Deploy

Após aprovação:

Merge via CodeCommit (rebase)
Branch deve ser marcada para deletar automaticamente
Sempre fazer a mesclagem do código com "Fast forward merge"
CI/CD faz deploy automático para staging
Teste sua feature em staging

7. Deploy para Produção

Quando staging estiver testado e aprovado:

Repetir o processo:

Abrir o PR de dev para main.
Code Review
Mesclar o código e Deploy

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

Nomenclatura de branches: - hotfix/ISSUE-456-bug-description - Bug fix(Utilizado somente no fluxo de hotfix)

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)"

Convenção de Commits (Conventional Commits):

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

[optional body]

[optional footer]

Types:

fix: Bug fix

Exemplos:

git commit -m "fix(api): handle null response from external service"

3. PR para main

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

Abrir PR:

Source: branch criado para o hotfix
Destination: main
Preencher titulo e descrição.
Aguardar code review

4. Deploy para Produção

Deploy automático para production após aprovação do code review
Monitorar intensivamente por 30 minutos
Verificar que bug foi resolvido

5. 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}

Pegar um Commit e trazer para outra branch

# 1. Entre na branch onde o código está originalmente, neste exemplo seria a main
git checkout main

# 2. Liste os commits para achar o ID (hash) da alteração que você quer
# (O terminal mostrará algo como: 7a2f3c1 "Fix(auth): corrige erro de login")
git log --oneline

# 3. Mude para a branch que vai receber a alteração
git checkout feature/login

# 4. Aplique o commit desejado usando o hash identificado no passo 2
git cherry-pick 7a2f3c1

# 5. (Opcional) Envie a alteração para o repositório remoto
git push origin feature/login

Regras e Boas Práticas

✅ Fazer

✅ Commits atômicos e bem descritos
✅ Rebase antes de abrir PR
✅ Branches de curta duração (máx 1 sprint)
✅ Testes antes de push
✅ Code review antes de mesclar o código
✅ Deletar branch após mesclar o código
✅ 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

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: 2-5 dias. Máximo: 15 dias(1 sprint). 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.