10.2.3 Descrição de um Pull Request
A descrição do Pull Request (PR) é um espaço para explicar em detalhes as mudanças feitas no código. Assim como a descrição de uma Issue, ela ajuda a equipe a entender o contexto da alteração, os problemas resolvidos e os impactos que podem ocorrer. Uma boa descrição facilita a revisão, melhora a colaboração e documenta as mudanças para o futuro.
Boas Práticas
1. Descreva o Problema e a Solução
Explique qual era o problema e como foi resolvido. Dê contexto suficiente para que quem revisa não precise adivinhar o que motivou a mudança. Se houver contexto adicional, como discussões prévias ou decisões do time, inclua essas informações.
2. Objetividade, mas com Completude
Dê informações suficientes para a revisão sem entrar em detalhes desnecessários. Seja claro sobre o que mudou e por quê.
3. Explique a Motivação da Mudança
Além de descrever o que foi feito, é importante explicar por que a alteração foi necessária. Isso ajuda a equipe a entender o contexto e a tomar decisões melhores no futuro. Se a mudança resolve um problema específico ou melhora um fluxo, deixe isso claro na descrição.
4. Adicione Capturas de Telas ou GIFs
Se a alteração impacta a interface gráfica ou muda fluxos visuais, adicionar imagens ou GIFs pode facilitar a revisão.
5. Explique Decisões Importantes
Se alguma escolha no código não estiver óbvia, comente na descrição para ajudar quem está revisando.
6. Siga o Padrão do Repositório
Assim como para o título do PR, é essencial seguir as diretrizes do repositório para garantir que sua contribuição seja bem recebida. Isso facilita a revisão e mantém a consistência do projeto. Antes de abrir um PR:
Verifique se há um arquivo
CONTRIBUTING.md, que pode conter instruções específicas.Observe PRs já abertos para entender como as descrições são estruturadas.
Caso exista um template de PR, preencha todas as informações solicitadas e siga o formato indicado.
Manter um padrão no projeto agiliza a revisão, melhora a colaboração e torna o histórico de mudanças mais organizado.
7. Use Palavras-chave para Fechar Issues
Ao criar um PR que resolve uma Issue, você pode usar palavras-chave para referenciá-la automaticamente. O GitHub fechará automaticamente a Issue quando o PR for mesclado. As palavras-chave disponíveis são:
Fixes #123(Corrige a Issue #123)Closes #456(Encerra a Issue #456)Resolves #789(Resolve a Issue #789)
Qualquer uma dessas palavras pode ser utilizada para referenciar e fechar a Issue correspondente. Mais detalhes podem ser encontrados na documentação oficial do GitHub.
8. Utilize Markdown
O Markdown facilita a visualização e organização das informações na descrição do PR, tornando o conteúdo mais legível. Assim como nas Issues, a descrição do PR aceita Markdown para formatação, e é possível visualizar o preview antes de enviar.
Exemplos de Boas Descrições ✅
Exemplo 1: Correção de bug
Exemplo 2: Nova funcionalidade
Contra-exemplos ❌
Deixar a descrição vazia.
"Correção de bug" → Qual bug? Onde? Como foi resolvido?
"Melhorias no sistema" → Muito genérico.
"Novo endpoint" → Qual endpoint? Para quê?
Uma descrição bem feita melhora a colaboração e torna o histórico do projeto mais organizado. Seguir boas práticas faz com que PRs sejam revisados mais rapidamente e evita retrabalho. Sempre siga os padrões do repositório e aproveite os recursos do Markdown para deixar suas descrições mais claras!
Atualizado
Isto foi útil?