TrackerJo/descrição-de-pr

Descrições de PR em inglês simples

Escreva para um mantenedor que precisa entender a mudança rapidamente. Uma boa descrição responde a três perguntas em sua primeira tela:

1. O que estava errado ou faltando?
2. Por que precisava mudar?
3. O que é verdade agora?

Leia o diff real, o corpo atual do PR, os commits, os testes e o estado do PR antes de escrever. O corpo antigo e os títulos dos commits descrevem intenção, não prova. Não alegue testes manuais, implantação ou comportamento de produção a menos que o autor tenha confirmado.

Abertura obrigatória: O que mudou e por quê

Toda descrição de PR deve começar com uma seção ## O que mudou e por quê de propriedade do contribuidor, imediatamente após a seção ## Status de propriedade do monitor, quando Status estiver presente. Isso é obrigatório, não formatação opcional.

Use três parágrafos curtos e rotulados, nesta ordem:

• Problema: a falha real do usuário ou operador, ou comportamento ausente.
• Por que essa mudança foi necessária: por que essa falha importava e por que o limite escolhido é necessário.
• Novo status quo: o comportamento concreto após este PR.

Mantenha cada parágrafo rotulado com uma ou duas frases. Um mantenedor deve ser capaz de responder “o que aconteceu neste PR?” apenas a partir desta seção. Não comece com mecânica de implementação, um design descartado ou reescreva o histórico.

Ao revisar uma abertura inadequada, forneça uma substituição concreta ou um esboço conciso de três parágrafos adaptado ao diff real. Não diga apenas que é verboso, pouco claro ou precisa de uma explicação melhor.

Use este formato para a maioria dos PRs:

## O que mudou e por quê

**Problema:** [A falha real do usuário ou operador, ou comportamento ausente.]

**Por que essa mudança foi necessária:** [Por que isso importava e por que esse limite é necessário.]

**Novo status quo:** [O comportamento concreto após este PR.]

## Após o merge

[Apenas as ações reais do operador ou revisor que restam. Omita esta seção se não houver nenhuma.]

## Verificação

[Indique apenas verificações manuais confirmadas e verificações genuinamente pós-merge.]

Comece pela substância. Não reafirme o título do PR, adicione uma introdução ou escreva um resumo que repita o próximo parágrafo.

O que manter

• Um estado final claro por mudança material. Um leitor que escaneia a primeira frase de cada parágrafo ou marcador deve entender o que muda após o merge.
• Decisões reais. Nomeie uma alternativa rejeitada apenas quando ela afeta o comportamento do produto, risco ou um custo significativo. Diga o que foi escolhido e por que em uma frase. Não invente um rótulo "Decisão chave".
• Fatos operacionais. Mencione migrações, backfills, trabalhos agendados, integrações, segredos, ordem de implantação e comportamento de falha quando um revisor ou operador precisar agir com base neles.
• Verificação honesta. Separe o que alguém realmente verificou manualmente do trabalho que deve realmente esperar até após o merge. Não liste comandos de lint, build, CI ou teste. Testes podem ser mencionados em inglês simples quando cobrirem um comportamento significativo.
• Chamadas abertas. Inclua apenas decisões não resolvidas que o revisor deve tomar. Coloque a pergunta primeiro, depois uma recomendação e seu custo. Omita a seção quando não houver nada a decidir.

Evidência necessária para sistemas alterados

Uma descrição está incompleta quando altera um sistema voltado ao usuário, um fluxo de trabalho material do operador ou sua configuração e não mostra ao revisor como inspecioná-lo.

• Capturas de tela ou vídeos curtos: Coloque a evidência visual em sua própria seção ## Evidência visual. Inclua capturas de tela para uma tela alterada ou vídeos curtos para uma interação alterada ou fluxo de várias etapas. Incorpore a mídia ou link para um anexo estável do PR. As legendas devem dizer o que mudou e o que o revisor está vendo. Não substitua uma captura de tela de código fonte, relatório de teste ou tela não alterada. Coloque a evidência de telefone necessária antes da evidência de laptop para superfícies públicas e de eventos, e identifique cada viewport e estado testado. Siga a habilidade visual-proof para captura, upload e verificação do commit mais recente. Omita esta seção apenas quando o PR não tiver superfície visual ou interativa.
• Configuração, ambiente e migrações: Coloque apenas variáveis de ambiente, segredos, configurações de dashboard e migrações de banco de dados realmente adicionados, removidos, renomeados ou que alteram comportamento em ## Configuração. Comece com a única ação que um operador precisa realizar; mantenha a configuração externa comum em uma frase curta, por exemplo: Configure um monitor em <URL> e aponte-o para https://buildpurdue.org/api/health. Nenhuma alteração interna. Não preencha a seção com detalhes de polling, justificativas já explicadas em outro lugar ou links para runbooks duplicados. Para cada migração real, nomeie seu caminho supabase/migrations/ commitado, resuma a alteração de esquema/dados/política, declare requisitos de compatibilidade ou backfill e forneça o resultado confirmado da repetição npm run db:verify. Nunca imprima valores secretos. Omita a seção quando não houver alterações de configuração ou migração.
• Fluxos alterados: Use fluxogramas Mermaid para fluxos materiais que mudam. Um fluxo é material quando tem várias etapas, ramificações, retentativas, uma transferência entre sistemas ou um caminho de falha. Mostre o caminho alterado e seu comportamento de falha importante, usando rótulos simples que um revisor possa ler. Adicione um diagrama para cada fluxo alterado distinto. Não use um diagrama para uma renomeação de uma etapa ou um cálculo local trivial.

Estes são separados da explicação principal. A explicação diz por que a mudança existe; evidência, configuração e diagramas permitem que um revisor a inspecione.

Mantenha a legibilidade

• Por padrão, 250 palavras ou menos. Uma descrição pode ser mais longa quando o operador precisa de uma lista de verificação curta, mas cada frase deve merecer seu lugar.
• Use parágrafos curtos. Use marcadores apenas para uma lista real, como etapas de configuração restantes. Não transforme cada frase em um marcador rotulado.
• Coloque o problema, o porquê e o novo status quo em inglês normal. Diga quem faz o quê.
• Evite código bruto, consultas, fragmentos de configuração, códigos de status como substantivos, jargão, metáforas, exageros e travessões.
• Não explique cada mecanismo. Mantenha o comportamento que o revisor precisa saber.
• Não repita um fato em uma seção posterior. Se uma frase pode desaparecer sem perder informação, remova-a.

Status é de propriedade do monitor

Os contribuidores são donos de todas as partes da descrição do PR exceto ## Status. Não adicione, remova ou edite essa seção você mesmo. O monitor de PR do BuildPurdue é dono dela e a mantém alinhada com o estado atual da revisão.

Quando altera o Status, o monitor também publica um comentário de PR correspondente Atualização de Status:. Ele usa uma frase em inglês simples: uma próxima ação concreta pré-merge quando houver trabalho restante, ou Nenhum trabalho restante. quando não houver nada restante. O Status nunca pertence a um comentário de revisão de descrição voltado ao contribuidor.

Não use Status para ideias futuras opcionais, notas históricas, trabalho apenas pós-merge ou trabalho rastreado separadamente que não bloqueie este PR.

Quando mais estrutura é justificada

Adicione uma seção focada apenas quando ela carregar informações que não cabem na explicação principal:

• Banco de dados / migrações: o que deve ser executado, se os dados existentes permanecem compatíveis e se um backfill é necessário.
• Comportamento operacional: o que é executado, quando é executado, como as falhas são visíveis e o que um operador deve configurar.
• Verificação: verificações manuais confirmadas e verificações genuinamente pós-merge.
• Chamadas abertas: escolhas de produto ou risco não resolvidas.

Uma pequena correção de bug pode simplesmente usar:

## Causa raiz

## Correção

## Verificação

Antes de publicar

1. Verifique se cada alegação remonta ao diff atual, testes, estado do PR ou um comando que você executou.
2. Leia a primeira tela sozinha. Ela deve dizer claramente o problema, por que a mudança foi necessária e o novo status quo.
3. Remova narração histórica, logs de implementação no estilo changelog, explicações repetidas e trabalho não relacionado.
4. Confirme que qualquer migração, implantação, segredo, dashboard ou ação pós-merge é explícita e acionável.
5. Leia em voz alta novamente. Deve soar como uma pessoa explicando a mudança para um colega de equipe, não um relatório de auditoria.
6. Em cada push, compare o corpo com o novo diff e atualize-o quando o comportamento, a configuração restante ou o estado de verificação tiverem mudado.

Fonte

Edite esta cópia em .agents/skills/. O hook pre-commit a espelha em .claude/skills/pr-description/; não edite o espelho diretamente.