Pular para conteúdo

RFC-002: Adoção de Git Flow Simplificado com Rebase Obrigatório

Campo Valor
Status Aprovada
Author Arthur Ferreira
Created 2026-01-15
Updated 2026-04-10
Reunião 2026-04-10
Deciders Todo o time técnico

Status

Valores possíveis:

  • 🟡 Draft: RFC em elaboração, ainda não apresentada
  • 🔵 Em Revisão: RFC apresentada e em discussão na reunião
  • ✅ Aprovada: RFC aprovada pelo time, pronta para implementação
  • ❌ Rejeitada: RFC rejeitada após discussão
  • 🟠 Deprecada: RFC anteriormente aprovada mas não mais válida

Contexto e Problema

Atualmente nosso fluxo Git não está formalmente documentado, podendo causar:

  • Inconsistência: Cada desenvolvedor segue um fluxo diferente
  • Confusão: Não está claro quando usar rebase vs merge
  • Falta de clareza: Processo de hotfix não está definido
  • Riscos: Deploys podem ir para produção sem passar por staging
  • Dificuldade de onboarding: Novos membros não sabem qual fluxo seguir
  • Histórico poluído: Uso de merge commits torna o histórico confuso e difícil de navegar

Por que resolver isso agora?

  • Precisamos de previsibilidade nos deploys
  • Necessidade de ambiente de staging estável
  • Reduzir riscos de bugs em produção
  • Histórico limpo facilita debugging e code review

Impacto de não resolver

  • Continuar com processos informais e inconsistentes
  • Alto risco de bugs em produção
  • Dificuldade de rastrear o que está em cada ambiente
  • Perda de tempo com conflitos e problemas de Mesclar o código
  • Histórico Git confuso e difícil de navegar

Documentação relacionada: - docs/development/git-workflow.md - Workflow atual - docs/development/code-review.md - Processo de review

Proposta de Solução

Adotar Git Flow Simplificado com duas branches principais e rebase obrigatório para sincronização:

  • dev → Ambiente staging (Testes)
  • main → Ambiente production (código estável e aprovado)

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"

Fluxo de Feature

  1. Branch a partir de dev: feature/ISSUE-123-description
  2. Desenvolver a feature
  3. Rebase com dev antes do PR (OBRIGATÓRIO)
  4. PR para dev (code review + CI)
  5. Deploy automático para staging
  6. Testes com sucesso
  7. PR de dev para main
  8. Deploy para production

Fluxo de Hotfix

  1. Branch a partir de main: hotfix/bug-description
  2. Corrigir o bug
  3. PR para main (fast-track se crítico)
  4. Deploy para production
  5. Rebase dev com main (OBRIGATÓRIO)
  6. Deploy para staging

Regras Fundamentais

  • ✅ Sempre usar rebase (NUNCA merge) para sincronizar branches
  • ✅ PRs obrigatórios para dev e main
  • ✅ CI deve passar antes do merge
  • ✅ Feature branches de curta duração (máx 1 sprint)
  • ✅ Commits seguem Conventional Commits: type(scope): message
  • ✅ Rebase interativo para limpar histórico antes do PR

Rebase: Regra Obrigatória

Por que Rebase ao invés de Merge?

Benefícios do Rebase:

  • ✅ Histórico linear e limpo: Fácil de entender a evolução do código
  • ✅ Commits organizados cronologicamente: Ordem natural dos eventos
  • ✅ Facilita code review: Reviewer vê mudanças em sequência lógica
  • ✅ Reverts mais seguros: Reverter commits é mais previsível
  • ✅ Integração contínua real: Código sempre testado em cima da versão mais recente

Problemas do Merge:

  • ❌ Histórico poluído: Merge commits criam "diamantes" no grafo
  • ❌ Difícil de navegar: git log fica confuso com múltiplos merges
  • ❌ Conflitos postergados: Problemas só aparecem no merge final
  • ❌ Code review difícil: Mudanças espalhadas em múltiplos commits de merge

Fluxo 1: Feature

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:

  1. Acesse repositório no CodeCommit
  2. Clique em "Pull requests"
  3. Clique em Create pull request
  4. selecione o source(Sua branch criada para desenvolver) para o Destination(dev) e clique em compare.
  5. Preencha template do PR:
  6. Título claro

  7. Descrição do que foi feito

  8. 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 o merge 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:

Repita o processo, mas não exclua a branch de DEV:

  • Abrir o PR de dev para main.
  • Code Review
  • Merge 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 uteis

Atualizar a branch criada com a branch dev

# No seu feature branch
git checkout feature/ISSUE-123-description

# Buscar últimas mudanças
git fetch origin

# Rebase com dev
git rebase origin/dev

# Se tiver conflitos, resolver e continuar
# (ver seção "Resolvendo Conflitos")

# Force push (branch pessoal, ok fazer force push)
git push origin feature/ISSUE-123-description --force-with-lease

Boas Práticas de Rebase

DO ✅:

  • Fazer rebase frequentemente (diariamente se dev está ativo)
  • Usar --force-with-lease ao invés de --force
  • Resolver conflitos localmente, testar, depois push
  • Fazer commits atômicos que passam testes
  • Usar mensagens de commit descritivas

DON'T ❌:

  • Fazer rebase sem atualizar as branchs
  • Usar --force sem o --lease (pode sobrescrever trabalho de outros)
  • Rebase depois que PR já foi aprovado e revisado
  • Reescrever histórico de commits já mergeados em main
  • Fazer force push em branches compartilhadas

Git Aliases Úteis

Adicionar ao ~/.gitconfig:

[alias]
  # Rebase shortcuts
  rb = rebase
  rbi = rebase -i
  rbc = rebase --continue
  rba = rebase --abort

  # Update feature branch com dev
  update = !git fetch origin && git rebase origin/dev

  # Limpar histórico
  cleanup = rebase -i origin/dev

  # Force push seguro
  pushf = push --force-with-lease

  # Log bonito
  lg = log --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit

Alternativas Consideradas

Opção 1: Trunk-based Development

Descrição: Uma única branch main, feature flags para controlar releases

Prós: - Mais simples e ágil - Integração contínua verdadeira - Menos overhead de branches

Contras: - Requer feature flags implementadas (não temos) - Arriscado sem testes automatizados robustos (ainda estamos construindo) - Difícil reverter features parciais - Curva de aprendizado para o time

Custo/Esforço: Médio (requer implementar feature flags)

Por que não escolhemos: Não temos infraestrutura de feature flags e testes suficientes ainda.

Opção 2: Git Flow Completo

Descrição: Branches develop, main, release, hotfix, feature

Prós: - Muito estruturado e bem documentado - Suporta múltiplas releases simultâneas - Processo maduro e testado

Contras: - Overhead para time pequeno (2-5 pessoas) - Release branches desnecessárias (fazemos release contínuo) - Complexidade adicional sem benefício proporcional - Mais difícil de aprender e manter

Custo/Esforço: Alto (complexidade desnecessária)

Por que não escolhemos: Muita complexidade para nosso tamanho de time e cadência de releases.

Opção 3: GitHub Flow

Descrição: Apenas main, feature branches com deploy direto

Prós: - Muito simples - Usado por grandes empresas (GitHub, etc.) - Documentação abundante

Contras: - Não tem staging explícito - Todo PR vai direto para produção - Difícil fazer QA manual antes de produção

Custo/Esforço: Baixo

Por que não escolhemos: Precisamos de um ambiente de staging para QA manual.

Opção 4: Merge ao invés de Rebase

Descrição: Usar merge commits para sincronizar branches

Prós: - Mais familiar para alguns desenvolvedores - Preserva histórico completo (incluindo merges) - Não requer force push

Contras: - Histórico poluído com merge commits - Difícil navegar no git log - Code review mais difícil - Bisect menos efetivo

Custo/Esforço: Baixo

Por que não escolhemos: Rebase oferece histórico muito mais limpo e facilita manutenção do código.

Análise de Impacto

Impacto Técnico

Times afetados: - Todo time de desenvolvimento - Testes precisam usar staging consistentemente

Sistemas afetados: - CI/CD pipelines precisam ser atualizados - Proteção de branches no CodeCommit - Webhooks de deploy (se houver)

Dependências: - Configurar CI/CD para ambas as branches - Documentar processo para o time (incluindo rebase) - Treinar novos membros em workflow de rebase - Criar aliases e ferramentas para facilitar rebase

Impacto em Negócio

  • ✅ Redução de bugs em produção
  • ✅ Maior previsibilidade de deploys
  • ✅ Time de People pode testar em ambiente estável
  • ✅ Histórico limpo facilita debugging
  • ✅ Code review mais eficiente
  • ⚠️ Processo de deploy ligeiramente mais longo (mas mais seguro)
  • ⚠️ Curva de aprendizado para rebase (1-2 semanas)

Riscos Identificados

Risco 1: Time pode esquecer de fazer rebase

  • Mitigação: Documentação clara + code review + pre-commit hook que detecta merges
  • Impacto: Médio
  • Probabilidade: Baixa

Risco 2: Conflitos de rebase mais frequentes

  • Mitigação: Feature branches de curta duração, rebase frequente (diário)
  • Impacto: Baixo
  • Probabilidade: Média

Risco 3: Dev e main podem divergir

  • Mitigação: PRs de dev→main frequentes, monitoramento
  • Impacto: Médio
  • Probabilidade: Baixa

Risco 4: Force push acidental em branch compartilhada

  • Mitigação: Proteção de branches, usar --force-with-lease
  • Impacto: Alto
  • Probabilidade: Muito Baixa

Plano de Implementação

Fase 1: Configuração (Semana 1)

Tasks:

  • Documentar processo no development/git-workflow.md
  • Padronizar todos os projetos com as branchs principais
  • Configurar proteção de branches (dev e main)
  • Atualizar CI/CD para suportar ambas as branches
  • Criar PR template com checklist incluindo rebase
  • Criar git aliases úteis e distribuir para o time

Responsável: Arthur Ferreira Prazo estimado: 3 dias

Fase 2: Migração (Semana 1-2)

Tasks:

  • Configurar deploy automático de dev para staging
  • Testar fluxo completo com feature de teste
  • Migrar PRs abertos para o novo fluxo

Responsável: Arthur Ferreira Prazo estimado: 4 dias

Fase 3: Monitoramento (Semanas 3-4)

Tasks:

  • Monitorar adoção do processo
  • Acompanhar casos de conflito de rebase
  • Coletar feedback do time sobre rebase
  • Ajustar documentação conforme necessário
  • Resolver dúvidas e problemas
  • Pair programming para casos difíceis de rebase

Responsável: Todo o time
Prazo estimado: Contínuo

Métricas de Sucesso

Após 1 mês

  • ✅ 100% dos PRs seguem o novo fluxo
  • ✅ Zero deploys acidentais em produção
  • ✅ Staging reflete sempre a branch dev
  • ✅ Time se sente confortável com o processo
  • ✅ 90%+ dos PRs usam rebase corretamente
  • ✅ Histórico Git permanece linear em dev e main

Após 3 meses

  • ✅ Tempo médio de deploy reduzido (menos rollbacks)
  • ✅ Onboarding de novos devs mais rápido
  • ✅ Zero confusão sobre qual fluxo seguir
  • ✅ 100% dos PRs usam rebase
  • ✅ Code review 30% mais rápido (histórico linear)
  • ✅ Zero merge commits em histórico de dev/main

Decisão da Reunião

Data da Reunião: 10/04/2026

Participantes:

  • Maria Alice
  • Igor Santiago
  • Marcio vignoli
  • Arthur Ferreira

Discussão Principal:

Revisão e aprovação da proposta de um fluxo Git simplificado focou em branches principais, processos de desenvolvimento e regras fundamentais para consistência.

Fluxo Git Simplificado Proposto A reunião começou com a introdução de um fluxo Git simplificado para resolver problemas atuais, melhorar o histórico de código e garantir maior clareza processual. Foi acordado que a documentação seria ajustada para formalizar o fluxo e esclarecer o uso de rebase versus merge.

Definição de Branches Principais A proposta estabeleceu as branches dev para stage/testes e main como código estável em produção, exigindo Pull Request e code review obrigatórios para ambas. Também foram definidos fluxos separados para features (a partir de dev) e hotfixes (a partir de main) para gerenciar o desenvolvimento.

Regras e Sincronização de Branches Foi decidido utilizar rebase em vez de merge para sincronização e limitar feature branches a um prazo máximo de 1 sprint (15 dias) para garantir que sejam de curta duração. A documentação será ajustada, removendo repetições e integrando um link para o guia formal de Code Review.

Feedback Recebido:

  • Igor Santiago, informou que havia muito conteúdo repetido e que poderia ser revisto e simplificado
  • Todos concordaram com a revisão e aprovação

Ações Requeridas (se aplicável):

  • Arthur ficou responsavel de revisar e ajustar o documento.

Resultado: Aprovada

Referências