PR templates: padronizando descrições de mudanças

1. Introdução aos PR Templates no Contexto do Git

Pull Requests (PRs) são a espinha dorsal da colaboração em projetos Git modernos, especialmente em plataformas como GitHub, GitLab e Bitbucket. No entanto, sem uma estrutura clara, as descrições de PRs frequentemente se tornam inconsistentes, omitindo informações críticas para revisores e dificultando o rastreamento histórico de mudanças. É aqui que os PR templates entram em cena.

Um PR template é um arquivo de modelo que define a estrutura padrão para a descrição de um Pull Request. Quando um desenvolvedor abre um novo PR, a plataforma carrega automaticamente o conteúdo desse template no campo de descrição, guiando o autor a preencher seções específicas. A padronização traz benefícios imediatos:

  • Revisão de código mais eficiente: revisores encontram rapidamente informações essenciais como tipo de mudança, testes realizados e issues relacionadas.
  • Rastreabilidade: descrições uniformes facilitam buscas futuras e geração de changelogs automáticos.
  • Redução de erros: checklists obrigatórios evitam PRs quebrados ou incompletos.

É importante distinguir entre templates locais e remotos. Templates locais são arquivos .md armazenados no repositório (geralmente em .github/ ou docs/), enquanto templates remotos são configurados nas configurações do repositório na plataforma (GitHub, GitLab). Neste artigo, focaremos nos templates locais, pois são versionados junto com o código, garantindo consistência entre branches e colaboradores.

2. Estrutura Básica de um PR Template

Um template eficaz deve conter seções que cubram os aspectos mais comuns de uma mudança. Abaixo está um exemplo mínimo de template:

## Descrição

[Descreva brevemente o que este PR faz e por que é necessário.]

## Tipo de Mudança

- [ ] Correção de bug
- [ ] Nova funcionalidade
- [ ] Breaking change
- [ ] Refatoração
- [ ] Documentação

## Checklist

- [ ] Testes unitários foram adicionados/atualizados
- [ ] Lint passou sem erros
- [ ] Documentação foi atualizada (se aplicável)
- [ ] Código segue o estilo do projeto

## Issues Relacionadas

<!-- Liste as issues que este PR resolve, ex: Closes #123 -->

Note o uso de comentários HTML (<!-- -->) para fornecer instruções ocultas. Isso mantém o template limpo visualmente, mas orienta o autor sobre o que preencher em cada campo.

3. Onde e Como Armazenar PR Templates no Repositório

No GitHub, o caminho padrão para um único template é .github/PULL_REQUEST_TEMPLATE.md. Se você precisa de múltiplos templates (ex.: um para bugs, outro para features), crie um diretório:

.github/
  PULL_REQUEST_TEMPLATE/
    bug_fix.md
    feature.md
    release.md
    default.md

Para definir um template padrão, configure o arquivo PULL_REQUEST_TEMPLATE.md na raiz do diretório .github/. Alternativamente, você pode usar o arquivo docs/PULL_REQUEST_TEMPLATE.md ou configurar no próprio repositório via interface web.

No GitLab, o caminho equivalente é .gitlab/merge_request_templates/. Já no Bitbucket, os templates são configurados via arquivo bitbucket-pipelines.yml ou diretamente nas configurações do repositório.

4. Personalização com Variáveis e Placeholders

Embora os templates sejam estáticos, você pode utilizar placeholders que serão substituídos manualmente ou por ferramentas de CI. Exemplo:

## Descrição

**Branch de origem:** {branch_name}
**Commit base:** {commit_hash}
**Data de criação:** {date}

## Changelog

<!-- Descreva as mudanças em formato de bullet points -->

## Issue Relacionada

Closes #{issue_number}

Para automação, ferramentas como GitHub Actions podem pré-preenchecer esses campos. Por exemplo, um workflow pode extrair o nome da branch e o hash do commit e injetá-los no template via API.

5. Checklist e Boas Práticas para Revisão

O checklist é a parte mais valiosa de um PR template, pois força o autor a verificar pontos críticos antes da revisão. Exemplo robusto:

## Checklist de Qualidade

- [ ] Testes unitários passam (`npm test` ou `pytest`)
- [ ] Lint sem warnings (`eslint .` ou `flake8`)
- [ ] Cobertura de testes >= 80%
- [ ] Documentação README atualizada
- [ ] Breaking changes documentadas em CHANGELOG.md
- [ ] Código não introduz dependências desnecessárias
- [ ] Performance testada (se aplicável)

Cada item deve ser acionável e verificável. Evite itens vagos como "Código revisado". Prefira ações concretas.

6. Integração com Issues e Commits

Um PR template bem desenhado deve solicitar explicitamente o link para issues relacionadas. Isso permite que plataformas como GitHub fechem automaticamente issues quando o PR é mergeado (usando palavras-chave como Closes, Fixes, Resolves).

Exemplo de seção:

## Issues Relacionadas

- Closes #123
- Relacionado a #456

Além disso, incentive o uso de padrões de commit como Conventional Commits (feat:, fix:, chore:). Você pode incluir um campo no template para listar commits relevantes:

## Commits Principais

- `abc123` - feat: adiciona endpoint de login
- `def456` - fix: corrige validação de email

Para alinhar descrições locais e remotas, use git commit --template:

git commit --template=.github/COMMIT_TEMPLATE.md

Isso garante que a mensagem do commit siga o mesmo padrão do PR template.

7. Estratégias de Manutenção e Versionamento do Template

O template deve ser versionado como qualquer outro arquivo no repositório. Isso significa que mudanças no template passam pelo mesmo fluxo de revisão que o código. Exemplo de PR para alterar o template:

## Descrição

Atualiza o PR template para incluir campo de "Impacto em performance".

## Mudanças

- Adiciona seção "Impacto em Performance" no template
- Remove campo duplicado "Testes realizados"

## Checklist do Template

- [ ] Template testado em PR de exemplo
- [ ] Documentação atualizada (se houver)
- [ ] Revisão de pelo menos um colega

Ao versionar o template junto com o código, você garante que branches antigas mantenham templates antigos, evitando quebras de compatibilidade. Para releases, crie um template específico:

## Release Checklist

- [ ] CHANGELOG atualizado
- [ ] Versão incrementada (semver)
- [ ] Tags criadas
- [ ] Deploy realizado em staging
- [ ] Smoke tests passaram

8. Exemplos Práticos de PR Templates

Template para Correção de Bugs

## Descrição do Bug

[Descreva o comportamento esperado vs. real]

## Passos para Reproduzir

1. Acesse a página X
2. Clique em Y
3. Observe o erro Z

## Impacto

- [ ] Crítico (sistema quebra)
- [ ] Alto (funcionalidade principal afetada)
- [ ] Médio (funcionalidade secundária)
- [ ] Baixo (cosmético)

## Testes Realizados

- [ ] Teste manual no ambiente de dev
- [ ] Teste unitário para o cenário
- [ ] Teste de regressão

Closes #123

Template para Novas Funcionalidades

## Descrição da Feature

[Explique o que a feature faz e por que é útil]

## Breaking Changes

- [ ] Sim (descreva abaixo)
- [ ] Não

Se sim, detalhe as mudanças necessárias para migração:

## Testes

- [ ] Testes unitários para novos componentes
- [ ] Testes de integração
- [ ] Testes de aceitação (se aplicável)

## Documentação

- [ ] README atualizado
- [ ] Exemplo de uso adicionado

Closes #456

Template para Release Branches

## Changelog da Release

### Novas Features
- [Liste as features incluídas]

### Correções de Bugs
- [Liste os bugs corrigidos]

### Breaking Changes
- [Liste breaking changes]

## Checklist de Deploy

- [ ] Versão atualizada no package.json
- [ ] CHANGELOG.md atualizado
- [ ] Tag criada (vX.Y.Z)
- [ ] Deploy em staging verificado
- [ ] Rollback testado

Closes #789

Referências