O que é pull request e como funciona a revisão de código

Um dia útil. Esse é o prazo máximo que o guia de engenharia do Google considera aceitável para alguém responder a um pedido de revisão de código, segundo as práticas de revisão publicadas pelo próprio Google. Não é o prazo para aprovar, é o prazo para dar o primeiro retorno. Quem já esperou uma semana por um comentário num projeto sabe por que esse número existe: código parado envelhece, conflita com o trabalho dos outros e desanima quem escreveu.

O pull request (ou PR) é justamente o mecanismo que organiza essa conversa. Em poucas palavras, é um pedido formal para que as alterações feitas numa branch sejam incorporadas a outra, normalmente a principal. Só que o pedido vem acompanhado de tudo o que um revisor precisa para decidir: a diferença linha a linha, a descrição do que mudou, os testes automáticos e um espaço para comentários.

Este guia acompanha um PR do nascimento até o merge, etapa por etapa, e mostra onde ele costuma emperrar em cada uma.

Pull request não é recurso do Git, e isso confunde muita gente

O Git, sozinho, não tem um comando chamado pull request. Existe o git request-pull, que gera um resumo em texto para mandar por e-mail, mas o PR que você conhece, com tela, botões e comentários, é um recurso das plataformas de hospedagem: GitHub, GitLab (que chama de merge request), Bitbucket, Azure DevOps.

A documentação do GitHub sobre pull requests descreve o PR como uma proposta para mesclar um conjunto de alterações de uma branch em outra. O nome vem da perspectiva de quem mantém o projeto: você está pedindo que ele “puxe” (pull) as suas mudanças.

Na prática, isso significa que o PR vive no servidor, não na sua máquina. Você trabalha localmente, faz commits, envia a branch com git push e só então abre o pedido na interface web ou pela linha de comando da plataforma.

O caminho de um pull request, da branch ao merge

O roteiro abaixo vale para a maioria dos times que usam GitHub ou GitLab. Os nomes dos botões mudam, a lógica não.

1. Criar uma branch a partir da principal atualizada. git switch main, git pull e depois git switch -c corrige-calculo-frete.
2. Fazer commits pequenos e com mensagem clara. “Corrige arredondamento do frete para CEPs do Norte” diz mais do que “ajustes”.
3. Enviar a branch para o remoto. git push -u origin corrige-calculo-frete.
4. Abrir o PR apontando a branch de origem e a de destino, com título e descrição.
5. Esperar a integração contínua (CI) rodar testes, lint e build.
6. Receber a revisão: comentários, sugestões, aprovação ou pedido de mudanças.
7. Responder e ajustar com novos commits na mesma branch. O PR se atualiza sozinho.
8. Fazer o merge quando houver aprovação e os testes estiverem verdes, e apagar a branch.

Parece linear, mas cada etapa tem um ponto onde iniciantes tropeçam. Os próximos blocos tratam deles.

Antes de abrir: o tamanho do PR decide metade da revisão

Um PR de 40 linhas costuma ser revisado no mesmo dia. Um de 1.500 linhas fica esperando alguém ter “uma tarde livre”, que nunca chega. E quando chega, o revisor cansa na metade e aprova o resto no automático.

O guia do Google recomenda mudanças pequenas justamente por isso: são mais rápidas de revisar, mais fáceis de entender e, se derem problema, mais simples de reverter. Se a sua tarefa é grande, quebre em etapas que façam sentido sozinhas. Por exemplo, um PR só com a migração do banco, outro com a regra de negócio, um terceiro com a tela.

Outra armadilha comum é misturar assuntos. Você foi corrigir um bug e aproveitou para reformatar o arquivo inteiro. O revisor agora precisa procurar a correção real no meio de 300 linhas de espaços e aspas trocadas. Formatação vai num PR separado.

A descrição do pull request é o que o revisor lê primeiro

Muita gente deixa a descrição em branco ou escreve “conforme conversado”. O revisor, que talvez nem tenha participado da conversa, abre o diff sem saber o que procurar.

Uma descrição útil responde três perguntas:

• O que mudou e por quê, em duas ou três frases, com link para a issue ou o ticket.
• Como testar: o passo a passo para reproduzir o comportamento novo.
• O que merece atenção: “a parte delicada é a função de arredondamento, o resto é renomeação”.

Prints de tela antes e depois ajudam muito em mudanças visuais. E se o PR ainda não está pronto, abra como draft (rascunho). Assim o time vê o andamento sem receber notificação de revisão antes da hora.

Corrige arredondamento do frete para a Região Norte

Fecha #482. O cálculo usava duas casas antes de somar a taxa
regional, o que gerava diferença de R$ 0,01 em alguns CEPs.

Como testar: simular frete para 69900-000 com carrinho de R$ 89,90.
Atenção: a mudança em utils/moeda.js afeta também o checkout.

Quando o pull request fica vermelho antes de alguém olhar

Ao abrir o PR, a maioria dos projetos dispara verificações automáticas: testes unitários, análise estática, build, às vezes uma varredura de segurança. Se algo falha, o PR mostra um X vermelho e muitos times configuram a branch principal para bloquear o merge até tudo passar.

A primeira reação do iniciante é pedir ajuda no chat. Antes disso, abra o log da verificação que falhou. Em boa parte dos casos o problema é simples: um teste que dependia de uma data fixa, um import esquecido, uma regra de lint sobre linha comprida. Rodar os mesmos comandos na sua máquina antes do push (npm test, pytest, o que o projeto usar) evita essa ida e volta.

Hoje também é comum ter um revisor automático com IA comentando o PR antes dos humanos. O buildbase explicou como funciona o revisão automática do Claude Code e seus níveis de configuração. Ferramentas assim pegam deslizes óbvios, mas não substituem a pessoa que conhece a regra de negócio.

Durante a revisão: como ler e responder comentários

Na revisão, quem analisa pode deixar três tipos de resposta, conforme a página do GitHub sobre revisões de pull request: apenas comentar, aprovar ou solicitar alterações. A terceira trava o merge até ser resolvida, se o repositório estiver configurado para isso.

Comentário não é ordem (nem ofensa)

Muitos revisores marcam observações menores com prefixos como “nit:” (detalhe) ou “opcional:”. Isso sinaliza que você pode aceitar ou não. Já um comentário sobre segurança, perda de dados ou regra de negócio errada pede ação. Se discordar, explique o motivo com calma. Uma boa resposta técnica costuma encerrar a discussão em duas mensagens.

Responda cada ponto, mesmo que seja com um “feito”

O revisor volta ao PR e precisa saber o que foi atendido. Responder “ajustado no commit a3f9e1c” ou marcar a conversa como resolvida economiza uma segunda leitura completa. Evite reescrever o histórico com push --force durante a revisão sem avisar, porque os comentários podem perder a referência às linhas.

Revisor demorando: quando cobrar

Se passou um dia útil sem resposta, um lembrete educado no canal do time é aceitável. Melhor ainda é facilitar: PR pequeno, descrição completa e testes verdes reduzem a vontade de adiar.

Depois da aprovação: as três formas de concluir o merge

No GitHub, o botão de merge oferece três opções, e cada time escolhe a sua política:

Depois do merge, apague a branch remota (o próprio GitHub oferece o botão) e atualize sua cópia local. Branch esquecida vira lixo que confunde o próximo dev.

Os sinais de um pull request aprovado sem drama

O PR que passa rápido é aquele em que o revisor entende o objetivo em um minuto e confia nos testes em mais um.

Juntando o que foi dito, os PRs que andam mais rápido têm quase sempre as mesmas características: tratam de um assunto só, têm menos de algumas centenas de linhas, explicam o porquê na descrição, chegam com testes passando e trazem testes novos para o comportamento novo. Quem escreve assim ganha fama no time de “PR fácil de revisar”, e isso vale muito numa avaliação de dev júnior.

O próximo passo prático é simples: no seu próximo PR, antes de clicar em “Create”, leia o próprio diff do começo ao fim como se fosse o revisor. Você vai achar pelo menos um console.log esquecido. Para continuar estudando os termos que aparecem nesse fluxo, como branch, merge e commit, o glossário de programação do buildbase reúne todos em um lugar.