Neste guia
Um bom pull request em inglês ajuda quem revisa a entender o que motivou a mudança, o que foi feito e como conferir o resultado. Imagine um checkout que pode criar pedidos duplicados quando a primeira resposta demora e a aplicação reenvia a mesma requisição. O título pode ser Prevent duplicate orders when checkout retries. Ele nomeia o efeito da mudança e o cenário em que o problema aparece.
Dê contexto antes de listar mudanças
Explique em uma frase o comportamento que motivou o PR. Depois, descreva a decisão técnica em termos que façam sentido para alguém que acabou de abrir o diff. Nesse exemplo, o servidor já aceita uma chave de idempotência e o cliente passa a reutilizá-la ao repetir a mesma tentativa de checkout. Essa chave permite que o servidor reconheça a requisição repetida e devolva o resultado da tentativa original. Esse é um exemplo de como uma API pode tratar tentativas repetidas. Requisições idempotentes na documentação da Stripe
Uma issue relevante ajuda quem quiser ver o histórico. O GitHub Blog também orienta a deixar claro o propósito do PR e o tipo de feedback que você espera. GitHub Blog
Um exemplo completo de descrição em inglês
Context. If the server creates an order but the response times out, the checkout client may retry the request.
Change. This PR reuses the same idempotency key when the client retries a checkout attempt.
The server then returns the original order.
Testing. I added a regression test that simulates a timeout after the server creates the order.
The retry returns the same order ID.
Review focus. Could you check how we handle a retry after the checkout page reloads?
I added a regression test registra o teste que entrou com a mudança. Se você também fez um teste manual, descreva o ambiente e o que observou com I verified in staging that the retry returned the original order ID. Se uma parte ainda está em validação, registre quem vai conferir e qual cenário falta.
Peça uma revisão com um ponto de atenção
Could you review this PR? funciona como pedido geral. Acrescente o ponto em que o revisor pode ajudar com Could you check whether the retry flow handles a page reload? Use by 16:00 UTC se houver um prazo concreto.
No Slack ou no chat do time, inclua o link e uma frase sobre a mudança. Isso dá contexto para a pessoa priorizar sua revisão. Como a thoughtbot pede revisão no Slack
Exercício de escrita
Pegue uma alteração pequena que você fez nesta semana. Escreva um título começando com Fix, Add ou Prevent e nomeie o comportamento que mudou. Em seguida, escreva uma frase de contexto, uma de validação e uma pergunta que aponte para um trecho específico do diff.
Leia a descrição em voz alta. Ela também serve como ponto de partida para explicar o PR na daily em inglês.