In questa guida

Una buona pull request spiega perché serve la modifica, che cosa cambia e come verificarla. Immagina che il client di checkout possa creare un secondo ordine quando la prima risposta va in timeout e il client ripete la richiesta. Potresti intitolare la PR Prevent duplicate orders when checkout retries. Il titolo indica il risultato della modifica e la situazione in cui si verifica il problema.

Dai a chi legge il contesto necessario

Spiega in una frase quale comportamento ha motivato la PR. Poi descrivi la scelta tecnica in termini comprensibili a chi apre il diff per la prima volta. In questo esempio il server supporta già le chiavi di idempotenza e il client riutilizza la stessa chiave ogni volta che ripete la richiesta per quel tentativo di checkout. Così il server riconosce la richiesta ripetuta e restituisce il risultato originale. La documentazione dell’API di Stripe mostra come usare queste chiavi per riconoscere le richieste ripetute. Richieste idempotenti nella documentazione di Stripe

Aggiungi il link a un’issue pertinente se chi legge potrebbe aver bisogno di ricostruire il contesto. GitHub consiglia anche di chiarire lo scopo della PR e il tipo di feedback che cerchi. Blog di GitHub

Un esempio completo di descrizione in inglese

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?

Con I added a regression test indichi quale test hai aggiunto insieme alla modifica. Se hai fatto anche una prova manuale, specifica l’ambiente e il risultato con una frase come I verified in staging that the retry returned the original order ID. Se resta uno scenario da verificare, indica quale e chi se ne occuperà.

Come chiedere una revisione mirata

Could you review this PR? è una richiesta generica. Indica su quale punto vuoi un secondo parere con Could you check whether the retry flow handles a page reload? Se c’è una scadenza precisa, aggiungi un orario come by 16:00 UTC.

Su Slack o nella chat del team, condividi il link con una frase che riassuma la modifica. Così chi legge ha abbastanza contesto per capire che priorità dare alla revisione. Come thoughtbot chiede una revisione su Slack

Esercitati a scrivere la prossima PR

Scegli una piccola modifica che hai fatto questa settimana. Inizia il titolo con Fix, Add o Prevent e indica quale comportamento cambia. Scrivi una frase di contesto, una su come hai verificato la modifica e una domanda che indirizzi chi legge verso un punto preciso del diff.

Leggi la descrizione ad alta voce. Puoi usarla anche per spiegare la PR alla daily in inglese.