En esta guía

Un buen pull request ayuda a quien lo revisa a entender qué cambió, por qué y cómo comprobar el resultado. Imagina que el servidor crea un pedido, pero la respuesta tarda demasiado y el cliente vuelve a enviar la solicitud, lo que puede generar un pedido duplicado. Podrías titular el PR Prevent duplicate orders when checkout retries. Ese título indica qué evita el cambio y en qué situación aparece el problema.

Da contexto antes de detallar el cambio

Explica en una frase qué comportamiento motivó el PR. Después, describe la decisión técnica de modo que alguien pueda entenderla al abrir el diff por primera vez. En este ejemplo, el servidor ya acepta claves de idempotencia y la aplicación cliente reutiliza la misma clave cuando vuelve a enviar esa solicitud. Así el servidor reconoce la solicitud repetida y devuelve el resultado original. La documentación de Stripe muestra cómo su API usa claves para reconocer los reintentos. Solicitudes idempotentes en la documentación de Stripe

Enlaza la issue correspondiente si quien revisa el PR necesita más contexto. GitHub también recomienda explicar el propósito del PR y qué tipo de comentarios esperas. Blog de GitHub

Un ejemplo completo de descripción en 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 indica qué tipo de prueba añadiste con el cambio. Si también hiciste una prueba manual, menciona en qué entorno la hiciste y qué resultado observaste. Por ejemplo, I verified in staging that the retry returned the original order ID da a quien revisa el PR un resultado que puede comprobar. Si aún quedan pruebas pendientes, indica qué caso falta por comprobar y quién se encargará.

Pide que revisen una parte concreta

Could you review this PR? funciona como petición general. Para señalar la parte que quieres que revisen, añade una pregunta como Could you check whether the retry flow handles a page reload? Si hay un plazo, incluye una hora concreta con by 16:00 UTC.

Cuando pidas la revisión por Slack o por el chat del equipo, comparte el enlace y resume el cambio en una frase. Así le das a la otra persona el contexto necesario para priorizar la revisión. Cómo pide thoughtbot que revisen un PR por Slack

Practica con tu próximo PR

Elige un cambio pequeño que hiciste esta semana. Empieza el título con Fix, Add o Prevent e indica qué comportamiento cambia. Escribe una frase de contexto, otra sobre cómo comprobaste el cambio y una pregunta que apunte a una parte concreta del diff.

Lee la descripción en voz alta. También te servirá para explicar el PR en la daily en inglés.