Pull requests

Uma pull request (PR), também chamada merge request no GitLab, é um pedido de integração: « eis o meu trabalho numa branch, por favor releiam-no e depois fundam-no em main ». É o ponto de encontro entre o código e a equipa.

Uma PR não é só um botão « fundir ». É um espaço de discussão em torno do código: comentários, sugestões, testes automáticos, validação. É aí que se joga a qualidade.

Antes de abrir uma PR, é preciso ter enviado a branch para o GitHub.

Etapa 1 — Enviar a branch:

git switch feature/recherche
git push -u origin feature/recherche

Etapa 2 — Abrir a PR (duas opções):

• Na interface GitHub: aparece uma faixa « Compare & pull request »; clica-se, escolhe-se a branch de base (main) e a branch comparada (feature/recherche).
• Na linha de comandos com o GitHub CLI:

# Cria a PR sem sair do terminal
gh pr create --base main --head feature/recherche \
  --title "Adiciona a pesquisa" \
  --body "Implementa a barra de pesquisa com filtros."

Uma boa descrição de PR contém:

O título e a descrição são lidos por pessoas com pressa. Seja explícito: « Corrige o crash no início de sessão » vale mil vezes mais do que « fix bug ».

🔧 Mini-exercício — A partir da branch corrente feature/recherche, crie uma pull request para main com gh, dando um título claro.

gh pr create --base main --head feature/recherche \
  --title "Adiciona a pesquisa" --body "Implementa a barra de pesquisa."

A revisão de código (code review) é o coração da PR: um ou vários colegas leem as alterações, fazem perguntas, sugerem melhorias e acabam por aprovar ou pedir alterações.

Os três vereditos possíveis no GitHub:

Do lado do autor, depois dos comentários, corrige-se e volta-se a enviar: a PR atualiza-se automaticamente.

# Corrigir na sequência da revisão
git switch feature/recherche
# ... alterações ...
git commit -am "Tem em conta os retornos da revisão"
git push          # a PR atualiza-se sozinha

O que um bom reviewer olha:

• O código faz o que pretende? (lógica correta)
• É legível e mantível?
• Há testes? A CI passa a verde?
• Há problemas de segurança ou de desempenho?

A revisão de código não é um juízo sobre a pessoa, mas uma melhoria coletiva do produto. Critica-se o código, nunca o autor. E também se sublinha o que está bem feito.

Quando a PR está aprovada e a CI a verde, funde-se. O GitHub propõe três métodos, que mudam a forma do histórico.

# Fundir a partir do terminal com o GitHub CLI
gh pr merge 42 --squash --delete-branch

Depois da fusão, limpa-se:

# Apagar a branch remota (muitas vezes automático)
git push origin --delete feature/recherche

# Atualizar o local
git switch main
git pull origin main

# Apagar a branch local
git branch -d feature/recherche

O squash and merge é muito popular: uma funcionalidade = um commit limpo em main. O histórico torna-se uma lista legível de funcionalidades, e não um emaranhado de « wip », « fix typo », « oups ».

🔧 Mini-exercício — Com gh, funda a PR número 42 em squash e apague a branch de seguida. Escreva o comando.

Uma PR eficaz é uma PR pequena, clara e testada. Eis os hábitos das equipas performantes.

# Ligar automaticamente uma issue na descrição
gh pr create --title "Adiciona exportação CSV" \
  --body "Permite exportar os dados em CSV. Closes #57"

Uma PR de 1 000 linhas recebe um « LGTM » (looks good to me) sem verdadeira releitura — ninguém tem coragem de ler tudo. Uma PR de 50 linhas recebe retornos preciosos. Pequeno = relido a sério.

🔧 Mini-exercício — Que palavra-chave acrescenta na descrição de uma PR para fechar automaticamente a issue #57 na fusão?

Question 1

Para que serve uma pull request?

a) Para apagar uma branch

b) Para pedir a releitura e a integração de uma branch noutra

c) Para instalar o Git

d) Para clonar um repositório

Question 2

O que é preciso fazer antes de poder abrir uma PR no GitHub?

a) Apagar main

b) Enviar a branch para o repositório remoto (git push)

c) Fechar o terminal

d) Desativar a CI

Question 3

O que significa « Request changes » numa revisão?

a) O código está aprovado

b) São necessárias correções antes da fusão

c) A PR é apagada

d) É criado um novo repositório

Question 4

Que método de fusão esmaga todos os commits da branch num só?

a) Create a merge commit

b) Squash and merge

c) Rebase and merge

d) Cherry-pick

Question 5

Por que privilegiar pequenas pull requests?

a) Consomem menos disco

b) São relidas mais depressa e com mais seriedade

c) O GitHub torna-as obrigatórias

d) Evitam escrever testes

Instrução

Terminou uma funcionalidade na branch feature/footer. Realize o ciclo completo de uma pull request com o GitHub CLI (gh):

1. Envie a branch.
2. Abra uma PR para main com um título claro e uma ligação de issue (Closes #12).
3. Depois de aprovada, funda-a em squash e apague a branch.
4. Atualize o seu repositório local.

Correção

# 1. Enviar a branch
git switch feature/footer
git push -u origin feature/footer

# 2. Abrir a pull request
gh pr create --base main --head feature/footer \
  --title "Adiciona o rodapé do sítio" \
  --body "Adiciona um footer responsivo com ligações e menções legais. Closes #12"

# 3. Depois da aprovação: fusão em squash + apagar a branch
gh pr merge --squash --delete-branch

# 4. Atualizar o local
git switch main
git pull origin main
git branch -d feature/footer

Resultado esperado:

$ git log --oneline -1
a1b2c3d Adiciona o rodapé do sítio (#13)

O número entre parênteses (#13) é acrescentado automaticamente pelo GitHub: é o número da PR. Clicar nele leva a toda a discussão da revisão. Rastreabilidade total.

Pontos a reter

1. Uma pull request pede a releitura e depois a fusão de uma branch: é um espaço de discussão.
2. Criar uma PR: enviar a branch e depois abri-la via a interface ou gh pr create.
3. A revisão de código resulta em Approve, Request changes ou Comment; critica-se o código, não o autor.
4. Três métodos de fusão: merge commit, squash and merge, rebase and merge.
5. Boas práticas: PR pequenas, um só assunto, CI verde, issue ligada.
6. Depois da fusão: apagar a branch e atualizar o local.

A continuação

Domina o ciclo de contribuição no seu repositório. A lição 04 — Workflow colaborativo abre a colaboração mais ampla: fork, clone, issues e boas práticas de equipa.