PR explainer
Produza um documento que ensine a um colega de equipe uma alteração: o que estava errado ou faltando, como o sistema funciona ao redor dela, o que a alteração faz e como sabemos que funciona.
Argumentos
- Alvo: um número ou URL de PR, ou nada.
- Com um PR e a CLI
ghdisponível, obtenha os detalhes comgh pr view <url> --json title,url,body,baseRefName,headRefName,headRefOid,filese o diff comgh pr diff <url>. Leia o código circundante no commit de cabeça do PR (git show <headRefOid>:<path>), não noHEADlocal. - Sem um PR ou sem
gh: explique a alteração local. Usegit diff <base>...HEADpara commits egit diffmaisgit statuspara trabalho não commitado, onde<base>é o branch padrão ou o primeiro commit.
- Com um PR e a CLI
--local: use o checkout local mesmo quando um PR existir (trabalho não enviado). Anote na página que reflete alterações locais.--concise: uma versão curta que leva cerca de dois minutos. No máximo um visual, no máximo 3 trechos de código, sem sumário, 1–3 frases por seção.--md: escreva Markdown em vez de HTML (arquivo padrãoHANDOVER.mdna raiz do repositório, a menos que o usuário nomeie um). Use isso para transições e quando um navegador não estiver disponível.
Público e tom
- O leitor é um engenheiro júnior da equipe. Use frases curtas, verbos simples, uma ideia por parágrafo.
- Não defina conceitos básicos (REST, SQL, JWT, hooks React) e não use analogias não técnicas. Mantenha-o técnico, com nomes reais de módulos, funções, rotas e campos, e números reais.
- Torne o texto simples, não o conteúdo. Explique uma chamada ou padrão de biblioteca incomum onde ele aparecer pela primeira vez.
- Escreva como um rascunho final. Descreva o estado atual diretamente. Sem registro de alterações ou texto do tipo "pensamos anteriormente".
- Seja honesto sobre a certeza. Rotule alegações não comprovadas como "provável, ainda não confirmado".
Escopo: explique a alteração, não o diff
- Escolha os arquivos que contam a história e, dentro deles, apenas as linhas que importam.
- Use 1–3 trechos por arquivo, cada um com menos de ~25 linhas, com
...para partes omitidas. Dê a cada um o caminho do arquivo e 2–4 frases sobre o que faz e por quê. - Para uma correção, mostre o código que causou o bug e o diff da correção.
- Ordene o código pelo fluxo de execução, não pela ordem do diff.
- Pule ajustes menores, renomeações e formatação. Mencione-os em uma linha se um revisor os vir no diff.
1. Entenda a alteração
- Leia o diff e o código circundante. Decida o modo:
- Funcionalidade: novo comportamento ou uma grande refatoração.
- Correção de bug: um sintoma, uma causa raiz e uma correção.
- Encontre a execução de verificação mais recente: comando de teste e contagens, e idealmente a prova de que um novo teste de regressão falha sem a correção e passa com ela. Se essa prova não existir e for barato, produza-a:
git stash push -- <arquivos src>, execute o teste, depoisgit stash pop. Procure também por uma verificação manual ou de ponta a ponta (saída de CLI, uma requisição, uma captura de tela). Mostre apenas a execução mais recente de cada. - Use descobertas da conversa (análise de causa raiz, relatório de QA, ticket) onde existirem.
2. Estrutura
Todo documento começa com uma linha de destaque (repositório · PR #n · ticket, ou repositório · alterações locais), um título em linguagem simples e uma introdução de 1–2 frases.
Correção de bug
- O que deu errado: o sintoma, onde foi visto, o que foi descartado.
- Causa raiz: o local exato onde os dados ou o fluxo quebram (
arquivo:linha), com um visual se ajudar. - O código que causou: um ou dois trechos.
- A correção: um trecho de diff e por que funciona. Nomeie efeitos colaterais que também corrige.
- Como sabemos: um teste de regressão que falha antes e passa depois, contagens da suíte completa, uma verificação manual.
- Conclusões: 2–4 lições que um júnior pode reutilizar em outro lugar.
Funcionalidade
- Por quê: o problema ou objetivo, com evidências.
- Onde se encaixa: contexto de arquitetura ou módulo (diagrama), mais o que intencionalmente não foi alterado.
- Como flui: passos ou um fluxograma vinculado aos cartões de código.
- Explicação do código: um cartão por arquivo importante, na ordem do fluxo.
- Comportamento a conhecer: casos limite, estados, modos de falha (uma tabela se houver mais de 3).
- Verificação: apenas a execução mais recente.
- Conclusão para o revisor: o modelo mental em 2–3 linhas e onde olhar com mais atenção no diff.
Acréscimos para transição (sempre incluídos com --md; opcionais em HTML):
- Como executar / testar: comandos exatos.
- Suposições feitas: decisões tomadas onde a especificação era omissa e por quê.
- Perguntas em aberto para o negócio: ordenadas por impacto.
- Riscos e reversão: o que poderia dar errado em produção e como reverter.
- Próximos passos: o que você faria com mais tempo.
Conciso: apenas O que deu errado / O que e por quê, Causa raiz / Como funciona, A correção / Código-chave e Como sabemos.
3. Visuais: apenas quando explicam algo que o texto não consegue
| Conteúdo | Uso |
|---|---|
| Arquitetura de módulo ou serviço, quem chama quem, sequência de requisição | flowchart / sequenceDiagram Mermaid (≤ ~12 nós) |
| Um branch que se comporta de forma diferente antes e depois | Tabela antes/depois ou um SVG estático pequeno |
| Dados passando por estágios, valores descartados por um filtro | Uma tabela de exemplos de entrada → saída, antes vs. depois |
| Estados, comandos, riscos, contratos | Tabelas |
Em Markdown, use blocos ```mermaid cercados (GitHub os renderiza). Adicione animações apenas se o usuário pedir.
4. Construção
- HTML: comece de
references/page-template.html(autocontido, modos claro e escuro, Mermaid e highlight.js de uma CDN). Salve em.pr-review/<nome>.html, nomeado pelo ticket ou PR, oulocal-<desc-curta>. Mantenha fora do git: segit check-ignore -q .pr-review/falhar, anexe.pr-review/a.git/info/exclude. Não edite.gitignorea menos que solicitado.- Trechos de código:
<pre><code class="language-<idioma>">…</code></pre>, escapados para HTML. Para um diff de correção, uselanguage-diffcom linhas-/+. - Mermaid:
<pre class="mermaid">…</pre>. Nunca codifique cores diretamente.
- Trechos de código:
- Markdown (
--md): Markdown simples no estilo GitHub, mesma estrutura, sem HTML.
5. Verificação única
- HTML: se uma ferramenta de navegador estiver disponível, abra a página uma vez na largura de desktop e uma vez em ~400px. Verifique se o Mermaid renderiza e o código está destacado, corrija o que viu em uma passada e não repita. Caso contrário, diga que não foi pré-visualizado e dê o comando para abri-lo (
openno macOS,startno Windows,xdg-openno Linux). - Releia cada
arquivo:linha, número e comando na página contra o código. Fatos devem ser exatos.
6. Relate
Responda com:
- o caminho do arquivo
- o modo, e as seções cobertas
- os visuais usados e o que cada um explica
- qual execução de verificação o documento mostra
- qualquer coisa rotulada como "ainda não confirmado"
Nunca edite o corpo de um PR, publique um comentário ou faça push sem perguntar primeiro.