GitHub Flow & PR workflow

Conhecer Git é necessário, mas não suficiente. A maior parte do seu trabalho como engenheiro sênior em time não é mexer em git rebase sozinho — é colaborar de forma que o resto do time consiga avançar com você sem se atrapalhar. Essa colaboração tem um nome convencional na indústria: pull request workflow. É o conjunto de práticas pelas quais mudanças propostas viram mudanças aceitas, no mais legível, revisável e seguro caminho possível.

Quem trata PR como "etapa burocrática antes do merge" perde a metade do valor. Quem trata como conversa técnica sobre design, espaço de aprendizado mútuo, e mecanismo de qualidade ganha cumulativamente. Times maduros têm PR culture que torna review uma das experiências mais formativas do dia. Times imaturos têm review como gargalo, ressentimento, e feedback raso. A diferença não é tempo investido — é como ele é investido.

GitHub Flow — o modelo simples que funciona

GitHub Flow é o workflow proposto pela própria GitHub em 2011, e adotado por enorme parte da indústria desde então. A regra é desconfortavelmente simples:

1. Branch main é sempre deployable.
2. Para qualquer mudança, crie um branch a partir de main.
3. Faça commits no seu branch.
4. Abra um Pull Request quando estiver pronto para discussão.
5. Após review e CI verde, merge no main.
6. Deploy.

Note o que não tem: nenhum branch develop, nenhum release/*, nenhum hotfix/*. A simplicidade é proposital — o overhead cerimonial do Git Flow é desnecessário quando main é deployable continuamente. Para times com CI/CD maduro, GitHub Flow é o caminho.

O tamanho do PR importa muito

A variável mais importante na qualidade de um PR é o seu tamanho. PRs grandes são quase inevitavelmente review ruim — e isso é estatisticamente bem-documentado. Estudos do Google e Microsoft mostram que efetividade de revisão cai dramaticamente após ~200 linhas de diff: revisores começam a "passar o olho" em vez de ler com atenção, deixam passar bugs óbvios, e dão feedback superficial.

A heurística prática:

• Até 100 linhas: revisão profunda fácil.
• 100-400 linhas: requer atenção mas factível.
• 400-1000 linhas: revisão começa a degradar; quebrar é aconselhável.
• 1000+ linhas: review virou teatro. Quase certamente passou bug.

Uma "feature" não-trivial frequentemente cabe em 5-10 PRs pequenos: um cria a interface, outro adiciona implementação básica, outro adiciona casos extra, outro adiciona telemetria, outro liga ao endpoint. Cada PR é verde, deployável, com escopo contido. Isso requer disciplina — e frequentemente feature flags para integrar peças incompletas — mas o ganho é grande.

Anatomia de um bom PR

Um PR bem-feito tem cinco partes que ajudam quem revisa:

1. Título descritivo

Mesma disciplina de mensagem de commit: imperativo, conciso, específico. "Add retry logic to PaymentClient" em vez de "updates" ou "fix bug". Lembre que esse título eventualmente vira parte do changelog ou release notes.

2. Descrição com contexto

Estrutura útil:

## Por quê
[Contexto: que problema isso resolve, motivação,
referência ao ticket/issue]

## O quê
[Mudanças principais. Bullet points são ok, mas seja
específica sobre intenção, não só listagem do diff]

## Como testar
[Passos para revisor reproduzir, ou link para teste
automático se claro o suficiente]

## Notas
[Decisões de design não-óbvias, trade-offs, alternativas
consideradas e descartadas]

Esse texto é especialmente valioso para mudanças não-triviais. Para PRs de uma linha (typo, lint), é overhead — não force. A regra: tanta descrição quanto for útil para quem vai revisar.

3. Commits limpos

Antes de abrir PR, limpe o histórico local com rebase interativo. Uma sequência de "WIP", "more fixes", "actually fix it" no histórico pollui a história permanentemente (mesmo após merge, se for via merge commit). Squash em commits atômicos antes de pedir review.

4. CI verde

Não submeta PR para review com CI vermelho. É desrespeitoso com o tempo do revisor — você está pedindo que ele revise código que você sabe que tem problema. Se está testando alguma coisa em CI antes do PR estar pronto, use draft PR (botão explícito no GitHub) que sinaliza "trabalho em andamento, ainda não revise".

5. Self-review antes de pedir review

Antes de marcar revisores, abra o seu próprio PR no GitHub e leia-o como se fosse de outra pessoa. Você vai pegar coisas: comentário desatualizado, debug print esquecido, função grande demais, nome ruim. Self-review é o momento em que você aplica a auto-crítica antes de gastar tempo de outros. ROI altíssimo.

Como fazer code review bem

Code review é tanto técnica quanto interpessoal. A versão técnica pergunta: o código está correto, está bem estruturado, está testável? A versão interpessoal pergunta: como dou feedback que ajuda em vez de aborrecer? Ambas importam.

O lado técnico — o que olhar

Hierarquia de prioridades em review:

1. Correção: faz o que diz que faz? Tem bugs? Casos extremos cobertos?
2. Segurança: introduz vulnerabilidade? Validação de input? Secrets em código? SQL injection?
3. Design: estrutura faz sentido? Coesão e acoplamento ok? Está respeitando convenções do codebase?
4. Testes: cobertura adequada para o que está mudando? Testes verificam comportamento, não implementação?
5. Performance: alguma operação O(n²) no caminho quente? Query N+1 no ORM? Alocação excessiva?
6. Legibilidade: nomes claros? Lógica fácil de seguir? Comentários onde necessário?
7. Estilo: convenções de código? Linter passou? (Se linter passou, não comente sobre formatting — é trabalho de máquina).

Quando bater conflito entre estilo e correção, foque em correção primeiro. Comentários sobre estilo em PRs com bugs são sintoma de revisor que está passando o olho.

O lado interpessoal — como comentar

Princípios que valem internalizar:

• Ataque o código, nunca a pessoa. "Esta função tem problema X" em vez de "você fez X errado".
• Faça perguntas em vez de afirmações quando estiver investigando. "Por que essa abordagem em vez de Y?" abre conversa; "isso está errado, use Y" fecha. Você pode estar errado — perguntar é humilde e prudente.
• Distinga "deveria" de "considere". Use prefixos como nit: (detalhe pequeno, opcional), suggestion: (proposta, mas não bloqueia), question: (estou tentando entender), blocker: (precisa resolver antes do merge). Convenção compartilhada economiza fricção.
• Elogie o que está bom. Identificar boas decisões é parte do review — reforça o que você quer mais. "Adorei a forma como você extraiu essa abstração" não é puxar saco; é feedback positivo específico.
• Limite-se ao que está no PR. Sugestões de "já que você está aqui, refatore isso outro também" são tentação clássica e péssima. Cria PRs gigantes, atrasa merge, frustra autor. Crie issue separada para outras coisas.

Como receber review

Receber feedback bem é tão importante quanto dá-lo. Princípios:

• Não leve para o pessoal. O comentário é sobre o código, não sobre você. Mesmo quando o tom é ríspido (e às vezes vai ser), extraia o conteúdo técnico.
• Responda a todos os comentários. Mesmo "ack, vou ajustar" ou "boa observação, vou pesquisar". Silêncio confunde — revisor não sabe se você viu, se concorda, se fez.
• Quando discordar, argumente. Você pode estar certa, e é importante defender. "Pensei nisso porque X; teu argumento foca em Y; acho que X tem prioridade aqui porque Z" é resposta produtiva.
• Quando concordar, mude. Não fique na defensiva teimosamente. Reconhecer que outra pessoa viu algo que você não viu é maturidade.

Conventional Commits — disciplina automatizada

Conventional Commits é uma convenção de mensagens que dá estrutura máquina-legível ao histórico:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Tipos comuns:

• feat: nova funcionalidade
• fix: correção de bug
• docs: mudança só em documentação
• style: formatação, sem mudança de lógica
• refactor: refatoração sem mudança comportamental
• test: adicionando ou corrigindo testes
• chore: manutenção, build, configs
• perf: melhoria de performance

Exemplos:

feat(auth): add support for refresh tokens

fix: prevent crash when user has no email

refactor!: rename UserService.find to findById

  BREAKING CHANGE: callers must update method name

O ! ou o footer BREAKING CHANGE: sinalizam mudanças incompatíveis. Ferramentas como semantic-release consomem isso para automaticamente bumpar versão (major em breaking, minor em feat, patch em fix), gerar changelog, e publicar releases. O custo é pequeno; o ganho em automação é grande.

Nem todo time adota Conventional Commits — funciona melhor em bibliotecas/SaaS publicado externamente. Para times internos, mensagens descritivas livres podem ser suficientes. Mas conhecer a convenção é útil — você vai encontrá-la em projetos open source.

CI/CD — o aliado silencioso

PR workflow só funciona bem com CI/CD funcionando bem. Mínimo aceitável em CI:

• Build: o código compila/parseia.
• Lint: estilo e padrões automatizados.
• Testes unitários: rodam em segundos.
• Testes de integração: rodam em poucos minutos.

Plus desejável:

• Type checking: mypy em Python, tsc em TS, etc.
• Análise estática de segurança: SAST (CodeQL, Semgrep, Snyk).
• Dependency scan: vulnerabilidades em pacotes (Dependabot, Renovate).
• Container scan: vulnerabilidades em imagens (Trivy).
• Mutation testing: para verificar qualidade de testes (em projetos críticos).

O ponto de tensão clássico: tempo de CI. Suíte de 30+ minutos significa que cada PR pequeno paga 30 min de espera para feedback. Time grande, muitas merges, fila acumula. Investir em paralelização, cache de dependências, testes mais rápidos é trabalho infraestrutural com retorno enorme. Times maduros têm engenheiros dedicados a isso (DevX, Developer Experience).

Branch protection — defesa explícita

No GitHub (e GitLab, e Bitbucket), você pode configurar branch protection em main: regras automatizadas que ninguém pode burlar acidentalmente:

• Exigir PR antes de merge (sem push direto).
• Exigir review aprovada de pelo menos N pessoas.
• Exigir CI verde antes de merge.
• Exigir que branch esteja atualizado com main antes de merge.
• Bloquear force-push.
• Restringir quem pode dispensar requirements (admin override).

Configurar isso uma vez, no início do projeto, evita uma série inteira de problemas. Mesmo em times pequenos onde "todos confiam um no outro", branch protection é red lines explícitas — protege contra erros acidentais (rebase no main esquecido, force push pra branch errada).

Como praticar

1. Faça self-review num PR seu antes de marcar revisores. Pegue um PR aberto seu, faça o exercício de ler como estranho. Anote o que muda. Em duas semanas, vai virar reflexo.
2. Ofereça-se para revisar PRs de áreas que você não conhece. Em codebase grande, sair da sua zona é onde você aprende. Comentar com perguntas em vez de afirmações funciona perfeitamente — você está de fato investigando.
3. Reescreva uma feature sua em PRs pequenos. Pegue uma coisa que você fez em 1 PR de 2000 linhas. Reflita: como isso teria sido em 8 PRs de 250 linhas? Faça o exercício mental — você vai ver onde a feature flag, onde o caminho incremental, onde a interface primeiro. Esse exercício muda como você desenha próximas features.

O Módulo 01 fecha aqui. Você passou de fundamentos de código (Módulo 00) para fundamentos de sistema — processos, memória, I/O, rede, Linux, containers, Git, colaboração. Esses dois módulos juntos formam a base sobre a qual os próximos sete módulos vão construir: testes, bancos, concorrência, AOP, cache, escalabilidade, resiliência, comunicação, observabilidade, segurança, cloud, AI-assisted, e por fim system design. A trilha é longa; o terreno foi preparado.