Fluxo de Pull Request no GitHub

Envie um PR que um revisor possa aprovar sem perguntas adicionais. O objetivo é ter um alto nível de informação no título e no corpo, evidências de que a mudança funciona e respostas limpas quando o feedback chegar.

Quando usar

• Você está prestes a abrir um PR para uma mudança que está funcionalmente completa.
• Um revisor deixou comentários e você precisa responder e enviar correções.
• Um PR está aberto há mais de um dia e precisa ser reestruturado (conflitos desatualizados, descrição ausente, verificação ausente).

Quando não usar

• A mudança ainda não está funcionalmente completa. Termine o trabalho primeiro; PRs em rascunho que são devolvidos na revisão geram ruído.
• O repositório usa um forge que não é o GitHub. Adapte-se às convenções desse forge; não force "GitHubismos".

Higiene do branch antes de abrir

• Faça rebase ou merge da base de destino para que a diferença esteja atualizada.
• Agrupe commits de "trabalho em progresso" (WIP) em unidades que possam ser revisadas. Prefira um commit por mudança lógica; não force um commit por PR se o trabalho for genuinamente multi-etapas.
• Confirme se os testes, a verificação de tipos e o lint passam localmente. Anote quaisquer omissões deliberadas no corpo do PR.
• Remova prints de depuração, código comentado e marcadores TODO que não estão sendo rastreados.

Título do PR

• Use o modo imperativo, com menos de 70 caracteres.
• Comece com a mudança visível para o usuário, não com o arquivo alterado. Allow CSV export from reports table é melhor que Update reports.tsx.
• Se o repositório usa uma convenção de prefixo de issue (PAP-1234:, [security]), siga-a.
• Não use ponto final no final.

Corpo do PR

Use esta estrutura:

## Summary
- 1–3 bullets describing what changed and why.

## Implementation notes
- Anything non-obvious in the diff: trade-offs, dropped alternatives, gotchas.
- Migration or config implications.

## Verification
- The exact commands or steps you ran.
- Screenshots or short clips for UI changes (required if pixels moved).
- Edge cases you exercised by hand.

## Risk and rollback
- What breaks if this is reverted, and how to revert cleanly.

Pule a seção Risk and rollback apenas para PRs claramente triviais (erros de digitação, documentação).

Evidência de verificação

• Testes passando no CI são necessários, mas não suficientes. Os revisores também precisam saber que a mudança se comporta corretamente de ponta a ponta.
• Para trabalho de UI, inclua capturas de tela do caminho principal e de um caso de borda. Marque os modos escuro e claro se o projeto suportar ambos.
• Para migrações, inclua um plano de "dry-run" (execução simulada) e os passos de reversão.
• Para mudanças de performance, inclua uma medição antes/depois, não adjetivos.

Respondendo a comentários de revisão

• Responda a cada comentário, mesmo que seja apenas "corrigido em <commit-sha>" — correções silenciosas deixam o revisor adivinhando.
• Envie correções como novos commits enquanto a revisão estiver ativa; não altere commits durante a revisão, a menos que o revisor concorde.
• Se você discordar de um feedback, diga isso com uma frase de justificativa e deixe o revisor decidir. Não escale por causa de comentários.
• Solicite a revisão novamente explicitamente após enviar as mudanças.

Checklist de merge

• Todas as verificações obrigatórias estão verdes.
• Todos os comentários de revisão foram resolvidos.
• Título/corpo do PR ainda estão precisos (atualize se o escopo mudou durante a revisão).
• A issue vinculada muda para in_review ou done de acordo com a convenção do projeto.
• Exclua o branch após o merge, a menos que seja um branch de integração de longa duração.

Antí-padrões

• Descrição do PR que diz "ver commits". Os revisores não deveriam precisar ler o log.
• Misturar refatoração e mudança de comportamento no mesmo PR sem separação no corpo.
• Commits de "endereçar feedback" que agrupam edições não relacionadas. Um commit por rodada de feedback é aceitável; um commit para tudo em andamento não é.
• Forçar push durante a revisão ativa sem avisar o revisor.