Pull Request: o que é, como funciona e por que é tão importante no GitHub

Pull request (PR) é uma solicitação feita para integrar as alterações de um branch em outro. No entanto, essa integração depende da análise e aprovação dos outros colaboradores do projeto. Se estiver tudo certo, as modificações são mescladas ao branch principal.

Na prática, enviar um pull request é como sugerir uma alteração em um documento compartilhado no Google Docs. 

Você não edita diretamente a versão final do arquivo. Em vez disso, propõe uma mudança, explica o motivo e aguarda a revisão e aprovação de outra pessoa.

É como se você dissesse: “terminei essa parte do código. Alguém pode revisar e, se estiver tudo certo, integrá-la ao projeto principal?”

Para que serve um pull request?

O PR é um processo comum em plataformas como GitHub, GitLab e Bitbucket. Isso porque ele:

• Permite que outros desenvolvedores revisem suas alterações antes que elas sejam incorporadas à base de código principal;
• Facilita a identificação de erros e a execução de testes automatizados, reduzindo as chances de bugs;
• Estimula discussões técnicas sobre o que foi implementado, com espaço para comentários, sugestões e ajustes;
• Registra quem fez o quê e por qual motivo, ajudando novos membros a entenderem a evolução do projeto;
• Contribui para manter a qualidade do código e evitar conflitos entre funcionalidades.

Ele também é um ótimo meio para receber feedback e evoluir como dev, especialmente em projetos open source.

Como funciona um pull request?

Quando você finaliza uma tarefa em um branch, cria um PR para sugerir que essas alterações sejam incorporadas a outro branch (geralmente o main). 

A plataforma exibe as diferenças entre os dois branches, permitindo que outros membros da equipe revisem o que foi modificado, façam comentários e aprovem (ou não) a proposta.

Na prática, ao criar esse PR, você está basicamente pedindo que outro desenvolvedor (geralmente o mantenedor do projeto) puxe (pull) as alterações feitas por você em um branch e as integre ao repositório principal do projeto.

Para que todo esse processo aconteça, o PR precisa de quatro informações:

• Repositório de origem: o local onde seu código modificado está armazenado (pode ser seu fork ou o repositório original);
• Branch de origem: a ramificação em que você fez as alterações;
• Repositório de destino: onde você deseja que suas modificações sejam adicionadas;
• Branch de destino: normalmente o main ou develop, onde o código final é mantido.

Como fazer um pull request no GitHub: passo a passo

Criar um pull request no GitHub é como contar uma história sobre o que você desenvolveu, por que fez isso e como sua equipe pode revisar com segurança antes de juntar ao código principal.

Veja como fazer isso passo a passo:

1. Acesse o repositório no GitHub

Entre na página principal do repositório em que você enviou sua branch com as alterações.

2. Selecione o branch com suas alterações

No menu suspenso de branches, localizado acima da lista de arquivos, selecione o branch no qual você fez os commits.

3. Clique em “Comparar e solicitar pull request”

O GitHub geralmente detecta que há mudanças entre seu branch e a base (geralmente main) e mostra uma faixa amarela com o botão “Comparar e solicitar pull request”. Clique nele para iniciar o processo.

4. Escolha os branches corretos

Use os menus suspensos para garantir que:

• O branch base (destino) seja o correto (geralmente main ou develop);
• O branch de comparação (origem) seja aquele onde você fez suas alterações.

Você pode ajustar essas opções nos menus suspensos, se necessário.

5. Preencha o título e a descrição da sua PR

Escreva um título claro e uma descrição objetiva explicando:

• O que foi alterado;
• Por que a alteração foi feita;
• Como testar as mudanças (se necessário).

Importante: nunca presuma que o revisor conhece o contexto do seu código. Escreva de forma que qualquer pessoa consiga entender o que está sendo feito, mesmo sem conhecer a base do projeto.

6. Organize seus commits como capítulos da história

Cada commit da sua branch deve funcionar como um “capítulo” claro da sua PR. Por isso, evite nomes genéricos como ajustes, teste ou update. Prefira mensagens de commit descritivas e padronizadas, como:

• feat: adiciona função de média ponderada com parâmetros validados
• fix: corrige erro no cálculo quando lista de pesos está vazia
• test: adiciona testes unitários para função media_ponderada

Se seus commits estiverem desorganizados, você pode usar git rebase -i para reordená-los, juntar etapas repetidas ou melhorar as descrições antes de criar o PR.

7. Crie o pull pequest

Primeiro, escolha o tipo de PR adequado. Você tem duas opções:

• Padrão: indicado quando o código está pronto para ser revisado;
• Rascunho (draft): ideal se você ainda estiver desenvolvendo a funcionalidade, mas quiser receber sugestões do time.

Depois de escolher a opção mais adequada, clique em “Criar Pull Request”.

8. Peça revisão e continue a conversa

Antes de chamar outras pessoas para revisar suas alterações, revise seu próprio código. Para isso:

• Verifique se os commits estão organizados e bem nomeados;
• Leia seu código como se fosse a primeira vez;
• Comente trechos que possam gerar dúvidas, deixando tudo mais claro para o revisor.

Agora, você pode marcar colegas ou líderes técnicos responsáveis pela revisão. Use @nomedousuário ou selecione um revisor nos campos da barra lateral.

O GitHub exibirá uma visão geral das alterações, commits e arquivos modificados. Você poderá acompanhar os comentários, adicionar novos commits e atualizar o PR até que ele seja aprovado.

Leia também:

Lovable: IA que cria sites e aplicativos sem precisar programar

Como aprovar um pull request?

Após revisar o código, verifique se todos os comentários foram resolvidos, se os testes passaram e se não há conflitos com a branch principal.

Se tudo estiver em ordem, o PR pode ser considerado aprovado. O próximo passo é fazer o merge, ou seja, mesclar o pull request ao branch principal.

Para isso, escolha o tipo de merge mais adequado:

• Merge Commit;
• Squash & Merge;
• Rebase and Merge;
• Ou siga a convenção adotada pelo seu time.

Após a mesclagem, você pode excluir a branch, caso ela não seja mais necessária.

O que acontece depois de um pull request ser aprovado?

Depois que um pull request é aprovado, o código é finalmente mesclado (merged) ao branch principal do projeto. Essa etapa oficializa a inclusão das alterações no repositório principal e marca a conclusão do ciclo de desenvolvimento daquela tarefa.

Dependendo da configuração do projeto, essa mesclagem pode automaticamente acionar pipelines de CI/CD, responsáveis por executar testes automatizados, realizar validações e até mesmo fazer o deploy da aplicação em ambientes de produção ou homologação.

Além disso, o PR aprovado fica registrado no histórico do projeto, com link direto para toda a discussão, comentários, arquivos modificados e justificativas. Isso facilita o rastreamento das decisões técnicas e contribui para a compreensão da evolução do código ao longo do tempo.

Exemplo prático de pull request em projeto Python

Para visualizar como um pull request funciona na prática, acompanhe este exemplo. 

Vamos supor que você está colaborando com um repositório chamado analise-vendas, que já possui uma função para calcular a média simples dos dados. 

Veja abaixo a estrutura básica desse projeto:

analise-vendas/
├── analise.py
├── test_analise.py
└── README.md

analise-vendas/
├── analise.py
├── test_analise.py
└── README.md

Nesse exemplo, o arquivo analise.py já contém a seguinte função:

# analise.py

def media_simples(valores):
    return sum(valores) / len(valores)

# analise.py

def media_simples(valores):
    return sum(valores) / len(valores)

Porém, o time identificou a necessidade de calcular a média ponderada, considerando pesos diferentes para cada item. 

Por esse motivo, você decide contribuir criando uma nova função chamada media_ponderada(), que calcula a média levando em conta o peso de cada valor.

Para isso, você segue o passo a passo abaixo:

Clona o repositório e cria uma nova branch

Você começa baixando o repositório para sua máquina e criando uma nova branch, garantindo que possa trabalhar com segurança sem alterar diretamente o código principal (main):

git clone https://github.com/seu-usuario/analise-vendas.git
cd analise-vendas
git checkout -b cc-adiciona-media-ponderada

git clone https://github.com/seu-usuario/analise-vendas.git
cd analise-vendas
git checkout -b cc-adiciona-media-ponderada

Faz a alteração no código

No arquivo analise.py, você implementa a nova função media_ponderada(). 

def media_ponderada(valores, pesos):
    if len(valores) != len(pesos):
        raise ValueError("Listas de valores e pesos devem ter o mesmo tamanho.")
    total = sum(v * p for v, p in zip(valores, pesos))
    return total / sum(pesos)

def media_ponderada(valores, pesos):
    if len(valores) != len(pesos):
        raise ValueError("Listas de valores e pesos devem ter o mesmo tamanho.")
    total = sum(v * p for v, p in zip(valores, pesos))
    return total / sum(pesos)

Adiciona um teste simples no arquivo test_analise.py

Agora, você cria (ou atualiza) um arquivo de teste, como test_analise.py, para garantir que sua função funciona corretamente.

from analise import media_ponderada

def test_media_ponderada():
    assert media_ponderada([10, 20, 30], [1, 1, 2]) == 22.5

from analise import media_ponderada

def test_media_ponderada():
    assert media_ponderada([10, 20, 30], [1, 1, 2]) == 22.5

Faz o commit e envia a branch para o GitHub

Após salvar tudo e confirmar que os testes passaram, você faz o commit das alterações e envia sua branch para o GitHub:

git add .
git commit -m "adiciona função media_ponderada e teste associado"
git push origin cc-adiciona-media-ponderada

git add .
git commit -m "adiciona função media_ponderada e teste associado"
git push origin cc-adiciona-media-ponderada

Cria o pull request 

Ao acessar o GitHub, o site detecta sua nova branch e sugere criar um pull request. Você clica no botão verde “Compare & pull request”.

Na tela de criação, você preenche:

• Título da PR: Adiciona função media_ponderada() ao módulo analise.py
• Descrição (explicando o quê, por quê e como):

### O que foi feito
Adicionada função `media_ponderada()` ao módulo `analise.py`.

### Por que foi feito
A função `media_simples()` não era suficiente para análises com diferentes pesos.

### Como testar
Executar `pytest` e verificar o teste `test_media_ponderada()` em `test_analise.py`.

### O que foi feito
Adicionada função `media_ponderada()` ao módulo `analise.py`.

### Por que foi feito
A função `media_simples()` não era suficiente para análises com diferentes pesos.

### Como testar
Executar `pytest` e verificar o teste `test_media_ponderada()` em `test_analise.py`.

Revisão e aprovação

Os membros da equipe acessam a aba “Files changed” no GitHub para visualizar um diff, ou seja, as diferenças entre o código antigo e o novo.

Na prática, essa aba faz uma comparação visual entre o antes e depois do código, facilitando a análise, os comentários, as sugestões de melhorias ou, simplesmente, a aprovação.

Exemplo de diff no GitHub:

+ def media_ponderada(valores, pesos):
+     if len(valores) != len(pesos):
+         raise ValueError("Listas de valores e pesos devem ter o mesmo tamanho.")
+     total = sum(v * p for v, p in zip(valores, pesos))
+     return total / sum(pesos)

+ def media_ponderada(valores, pesos):
+     if len(valores) != len(pesos):
+         raise ValueError("Listas de valores e pesos devem ter o mesmo tamanho.")
+     total = sum(v * p for v, p in zip(valores, pesos))
+     return total / sum(pesos)

Se tudo estiver certo, o PR é aprovado e mesclado (merged) para o branch principal.

Veja também:

Kivy e Python: vale a pena para seu projeto? Guia completo

Boas práticas ao criar um pull request

Criar um PR é uma oportunidade de comunicar claramente o que você desenvolveu, facilitar o trabalho do revisor e contribuir com qualidade para o projeto. Quanto mais clara e organizada for sua pull request, maiores as chances de ela ser revisada, compreendida e aprovada com agilidade.

Confira abaixo algumas boas práticas que podem te ajudar nesse processo:

Use uma branch de tópico com nome claro

Evite trabalhar diretamente no main ou develop. Em vez disso, crie uma nova branch para cada funcionalidade, correção ou tarefa.

O ideal é sempre usar nomes descritivos e, se estiver num projeto com várias pessoas, usar suas iniciais para identificar sua branch.

Por exemplo:

git checkout -b cc-funcao-media-ponderada

git checkout -b cc-funcao-media-ponderada

Evite push forçado em PRs abertas

Evite usar git push --force depois que a PR já estiver em revisão. Esse comando pode sobrescrever o histórico e causar conflitos com o trabalho de outros colaboradores.

Se for realmente necessário corrigir ou reorganizar os commits, fale com o time antes de realizar a alteração.

Escreva commits com títulos ativos e organizados

Cada commit é como um capítulo da sua história. Por isso, utilize palavras no imperativo e seja claro ao descrever as alterações realizadas.

Por exemplo:

• feat: adiciona tratamento para dados faltantes no ETL
• fix: corrige cálculo de médias com NaN
• docs: atualiza guia de estilo de código

Mostre visualmente o que foi alterado (quando possível)

Se o seu PR envolve interface, dados ou gráficos, facilite a vida do revisor:

• Tire prints das telas ou dos resultados;
• Grave GIFs animados com ferramentas como Giphy Capture ou Licecap;
• Cole imagens diretamente na descrição do PR no GitHub.

Ver o que mudou visualmente é muito mais rápido e eficiente do que obrigar o revisor a rodar tudo localmente.

Crie pull requests pequenas e frequentes

PRs menores são mais fáceis de revisar, compreender, testar e aprovar. Além disso, reduzem a chance de conflitos e evitam que funcionalidades fiquem bloqueadas aguardando análise.

Portanto, se sua PR ultrapassar 400 linhas de alteração, veja se não é melhor dividí-la em partes menores.

Como aprender versionamento de código e colaboração com Git e GitHub?

Agora que você já sabe o que é e como criar um pull request no GitHub, chegou a hora de colocar esse conhecimento em prática! Para isso, você precisa dominar o básico da programação e do versionamento de código.

O curso Git e GitHub – Controle de Versão e Colaboração da Asimov Academy oferece exatamente o que você precisa para dar esse primeiro passo.

Você vai entender como usar Git e GitHub na prática, incluindo a criação e revisão de PRs, o controle de versões e a colaboração em projetos reais.

Comece agora e aproveite essa oportunidade de crescer na programação!

Faça o curso:

Git e GitHub – Controle de Versão e Colaboração