A magia dos Pull Requests

1. Do merge à proposta: por que precisamos de Pull Requests?

Na aula passada aprendemos a mesclar (merge) branches no seu computador local. Isso funciona muito bem quando você trabalha sozinho. Mas e se uma equipe inteira estiver trabalhando no projeto? Se cada um for mesclar suas alterações diretamente na branch principal main, muito em breve começará o caos: alguém pode, por engano, adicionar código com bugs, quebrar a build ou apagar uma parte importante do trabalho de um colega.

Para evitar isso, no desenvolvimento em equipe adota-se outra abordagem. Em vez de mesclar as alterações imediatamente, você cria uma proposta de merge. Essa proposta se chama Pull Request (abreviado PR) ou, em algumas plataformas, Merge Request.

Pull Request — é um pedido formal: “Por favor, faça pull das minhas alterações a partir da minha branch e faça merge delas na branch principal”. Mas não é apenas um pedido; é uma verdadeira área para discussão, verificação e melhoria do código antes que ele chegue à main.

2. Fluxo de trabalho padrão com Pull Request

Vamos, passo a passo, ver como é o fluxo típico ao criar uma nova funcionalidade.

Antes de criar uma branch para a nova tarefa, garanta que você enviou todos os seus commits concluídos (push) e atualizou (Update Project) a branch principal main.

Caso contrário, todos os seus commits locais “esquecidos” da main podem acabar entrando no novo Pull Request, criando confusão para seus colegas.

Passo 1. Crie uma branch para a nova tarefa.

Como antes, todo novo trabalho começa com a criação de uma branch separada. Suponha que queiramos adicionar ao nosso projeto um arquivo com regras para contribuidores. Vamos criar a branch feature/add-contribution-guide.

Passo 2. Faça as alterações e envie sua branch para o GitHub.

Na nova branch, crie o arquivo CONTRIBUTING.md (após criar, clique em Add) e escreva nele uma mensagem para outros desenvolvedores. Em seguida, faça Commit and Push com uma mensagem clara, por exemplo: docs: Add contribution guide.

Este é um passo crucial! O Pull Request é criado com base na branch que já existe no servidor remoto. Portanto, antes de criar o PR, você precisa enviar (push) sua nova branch para o GitHub.

3. Criando um Pull Request pelo IntelliJ IDEA

Agora que sua branch está no GitHub, você pode criar o Pull Request.

Passo 1. Abra a aba Pull Requests.

À esquerda da IDE há a aba Pull Requests. Abra-a e clique no ícone + para criar um novo PR.

Passo 2. Preencha os dados do PR.

A IDE abrirá automaticamente uma interface prática para criar o Pull Request. Sua tarefa é preenchê-la corretamente. Vamos analisar os campos principais:

1. Título: a IDE frequentemente coloca aqui o nome da branch, mas isso é uma má prática. O título deve ser curto, claro e refletir a essência das mudanças, como uma boa mensagem de commit.
2. Descrição: aqui você explica o que e por que você fez.
3. Revisores: aqui você seleciona um ou mais colegas que devem revisar seu código. Em um projeto de estudo vamos pular esta etapa, mas, no trabalho real, ela é obrigatória.
4. Responsáveis: normalmente você indica a si mesmo. Isso significa que você é o autor e o principal responsável por essa tarefa e por aplicar as correções após a revisão.

Depois de preencher todos os campos, clique em Create Pull Request sem medo.

4. Code review: verificação e discussão

Após criar o PR, começa a etapa mais importante — code review. Seus colegas podem abrir seu PR, ver todas as mudanças e deixar comentários.

Você pode ver todas as discussões diretamente na IDE, na aba Pull Requests. Se alguém deixar um comentário, você receberá uma notificação.

O que fazer se pedirem alterações?

Muito simples! Não é preciso criar um novo PR. Basta fazer as alterações necessárias no código na mesma branch, criar um novo commit e enviá-lo (push). O Pull Request no GitHub será atualizado automaticamente, adicionando seus novos commits.

5. Finalizando: merge e exclusão da branch

Quando todos os comentários forem resolvidos e a equipe aprovar suas alterações, o Pull Request pode ser mesclado. Normalmente isso é feito por um desenvolvedor sênior ou por você mesmo, se tiver permissão.

Passo 1. Merge

O merge geralmente acontece no site do GitHub. Lá, abaixo do seu PR, aparecerá um grande botão verde Merge pull request. Depois de clicar nele, seu código passará a fazer parte da branch principal main.

Passo 2. Exclusão da branch.

Depois do merge, sua branch `feature` não é mais necessária e deve ser apagada para não poluir o repositório. O GitHub sugerirá isso automaticamente, exibindo o botão Delete branch.

Não se esqueça também de excluir a cópia local da branch na sua IDE, para manter a organização. Isso pode ser feito pelo mesmo menu de gerenciamento de branches.

6. Três regras de commit

Um bom commit não é apenas uma mensagem adequada, mas também um conteúdo adequado. Para que seu histórico de mudanças seja limpo, útil e profissional, siga três regras simples.

Regra 1: escreva mensagens claras seguindo um padrão

Seus commits são mensagens que você envia para sua equipe e para si mesmo no futuro. Um histórico repleto de mensagens “fix” ou “update” é absolutamente inútil. O padrão mais popular se chama Conventional Commits. Ele propõe a seguinte estrutura:

<type>: <short description>

O tipo é uma palavra curta que descreve a categoria das suas alterações:

• feat: (feature) — para nova funcionalidade.
• fix: — para correção de bug.
• docs: — para mudanças na documentação.
• style: — para ajustes de formatação que não afetam a lógica do código.
• refactor: — para mudanças no código que não adicionam funcionalidade nem corrigem bugs.
• test: — para adicionar ou corrigir testes.
• chore: — para tarefas rotineiras não relacionadas ao código (atualização de dependências, configuração de build).

Exemplos:

• Ruim: fixed bug
• Bom: fix: Correct user login validation

• Ruim: readme
• Bom: docs: Update installation instructions

Regra 2: um commit — uma alteração lógica (Atomicidade)

Não tente colocar no mesmo commit a correção de um bug, a adição de uma nova funcionalidade e o refatoramento de código antigo. Um commit assim é muito difícil de revisar e quase impossível de reverter sem dor, se algo der errado.

Cada commit deve resolver apenas uma tarefa específica.

• Ruim: um único commit com a mensagem “Update user page” que adiciona um campo de avatar, corrige um erro na validação do nome e muda a cor dos botões.
• Bom: três commits diferentes:
  1. feat: Add avatar upload to user profile
  2. fix: Correct username validation logic
  3. style: Update button colors on user page

Commits pequenos e focados são muito mais fáceis de entender e de gerenciar.

Regra 3: O commit não deve quebrar o projeto

Cada commit na branch principal deve manter o projeto em estado funcional. Antes de criá-lo, você deve ao menos garantir que o código compila. Mas como ter certeza de que você não quebrou algo em outra parte do sistema? Confiar apenas em verificação manual é arriscado.

É aqui que entra a automação. Neste curso não vamos configurar processos automáticos, mas você deve saber como isso funciona em projetos reais. As equipes modernas usam sistemas de integração contínua (Continuous Integration, CI), como o GitHub Actions.

Como isso funciona?

Você escreve o código e os testes correspondentes. Depois você configura um script especial (workflow) diretamente no GitHub. Agora, assim que você der push no seu Pull Request, acontece a mágica:

1. GitHub Actions detecta esse evento e inicia o seu workflow.
2. Ele automaticamente “constrói” o projeto e executa todos os testes.
3. Se todos os testes passarem, ao lado do seu commit no GitHub aparece uma marca de verificação verde. É um sinal para toda a equipe de que suas alterações são seguras.
4. Se pelo menos um teste falhar, você verá um x vermelho. Mesclar esse PR na branch principal é terminantemente proibido.

            graph LR
            subgraph GitHub
            A[Desenvolvedor] -- "push" --> B(Repositório)
            B -- "Evento: push" --> C{GitHub Actions}
            end

            subgraph Workflow
            C -- "Disparo" --> D[Execução de testes]
            D --> E[Sucesso]
            D --> F[Falha]
            end

            subgraph Notifications
            F --> G((Email))
            G --> H[Desenvolvedor]
            G --> I[Equipe]
            end

            style F fill:#f99,stroke:#333,stroke-width:2px
            style G fill:#ccf,stroke:#333,stroke-width:2px
        

É possível configurar notificações. Se os testes falharem, o GitHub Actions pode enviar um e-mail para você ou para toda a equipe. Essa abordagem cria uma cultura em que os testes não são apenas uma formalidade, mas uma parte indispensável do desenvolvimento, e cada um é responsável pela qualidade do próprio código.