Fluxo de Trabalho e Versionamento com Git

Visão Geral

O Git é sua rede de segurança. Trate commits como pontos de salvamento, branches como "caixas de areia" (sandboxes) e o histórico como documentação. Com agentes de IA gerando código em alta velocidade, o controle de versão disciplinado é o mecanismo que mantém as alterações gerenciáveis, revisáveis e reversíveis.

Quando Usar

Sempre. Toda alteração de código passa pelo Git.

Princípios Fundamentais

Desenvolvimento Baseado em Trunk (Recomendado)

Mantenha o main sempre pronto para deploy. Trabalhe em branches de funcionalidade de curta duração que façam o merge de volta em 1-3 dias. Branches de desenvolvimento de longa duração são custos ocultos — eles divergem, criam conflitos de merge e atrasam a integração. Pesquisas da DORA mostram consistentemente que o desenvolvimento baseado em trunk se correlaciona com equipes de engenharia de alto desempenho.

main ──●──●──●──●──●──●──●──●──●──  (always deployable)
        ╲      ╱  ╲    ╱
         ●──●─╱    ●──╱    ← short-lived feature branches (1-3 days)

Este é o padrão recomendado. Equipes que usam gitflow ou branches de longa duração podem adaptar os princípios (commits atômicos, pequenas alterações, mensagens descritivas) ao seu modelo de branching — a disciplina de commit importa mais do que a estratégia de branching específica.

• Branches de desenvolvimento são custos. Todo dia que um branch vive, ele acumula risco de merge.
• Branches de release são aceitáveis. Quando você precisa estabilizar um release enquanto o branch principal avança.
• Feature flags > branches longos. Prefira fazer deploy de trabalho incompleto por trás de flags em vez de mantê-lo em um branch por semanas.

1. Commite Cedo, Commite Frequentemente

Cada incremento bem-sucedido ganha seu próprio commit. Não acumule grandes alterações não commitadas.

Work pattern:
  Implement slice → Test → Verify → Commit → Next slice

Not this:
  Implement everything → Hope it works → Giant commit

Commits são pontos de salvamento. Se a próxima alteração quebrar algo, você pode reverter para o último estado conhecido e bom instantaneamente.

2. Commits Atômicos

Cada commit faz uma coisa lógica:

# Good: Each commit is self-contained
git log --oneline
a1b2c3d Add task creation endpoint with validation
d4e5f6g Add task creation form component
h7i8j9k Connect form to API and add loading state
m1n2o3p Add task creation tests (unit + integration)

# Bad: Everything mixed together
git log --oneline
x1y2z3a Add task feature, fix sidebar, update deps, refactor utils

3. Mensagens Descritivas

Mensagens de commit explicam o porquê, não apenas o o quê:

# Good: Explains intent
feat: add email validation to registration endpoint

Prevents invalid email formats from reaching the database.
Uses Zod schema validation at the route handler level,
consistent with existing validation patterns in auth.ts.

# Bad: Describes what's obvious from the diff
update auth.ts

Formato:

<type>: <short description>

<optional body explaining why, not what>

Tipos:

• feat — Nova funcionalidade
• fix — Correção de bug
• refactor — Alteração de código que não corrige um bug nem adiciona uma funcionalidade
• test — Adicionando ou atualizando testes
• docs — Apenas documentação
• chore — Ferramentas, dependências, configuração

4. Mantenha as Preocupações Separadas

Não combine alterações de formatação com alterações de comportamento. Não combine refatorações com funcionalidades. Cada tipo de alteração deve ser um commit separado — e idealmente um PR separado:

# Good: Separate concerns
git commit -m "refactor: extract validation logic to shared utility"
git commit -m "feat: add phone number validation to registration"

# Bad: Mixed concerns
git commit -m "refactor validation and add phone number field"

Separe refatoração de trabalho de funcionalidade. Uma alteração de refatoração e uma alteração de funcionalidade são duas alterações diferentes — envie-as separadamente. Isso torna cada alteração mais fácil de revisar, reverter e entender no histórico. Pequenas limpezas (renomear uma variável) podem ser incluídas em um commit de funcionalidade a critério do revisor.

5. Dimensionamento das Alterações

Mire em cerca de 100 linhas por commit/PR. Alterações acima de cerca de 1000 linhas devem ser divididas. Veja as estratégias de divisão em code-review-and-quality para saber como quebrar grandes alterações.

~100 lines  → Easy to review, easy to revert
~300 lines  → Acceptable for a single logical change
~1000 lines → Split into smaller changes

Estratégia de Branching

Branches de Funcionalidade

main (always deployable)
  │
  ├── feature/task-creation    ← One feature per branch
  ├── feature/user-settings    ← Parallel work
  └── fix/duplicate-tasks      ← Bug fixes

• Faça o branch a partir do main (ou do branch padrão da equipe)

…