Commits y pull requests en inglés claro
Un commit y una descripción de pull request son los dos textos en inglés que más vas a escribir en tu vida laboral. Los dos tienen una estructura fija, y saberla convierte una hoja en blanco en completar huecos.
Escribir en inglés cuesta cuando hay que inventar la forma además del contenido. La buena noticia es que en un commit y en una descripción de pull request la forma ya está inventada: las dos son plantillas con huecos, y el inglés que necesitan es corto, en presente y sin adornos.
Dicho de otro modo: no hace falta escribir bien en inglés para escribir un buen pull request. Hace falta saber qué va en cada hueco.
El commit: una línea que completa una frase
La convención de git es que el título completa la frase “if applied, this commit will…”. Por eso va en imperativo y sin punto final: es lo que el cambio hace, no lo que vos hiciste.
| Escrito así | Por qué falla | Mejor |
|---|---|---|
| Fixed login bug | Pasado: describe tu tarde, no el cambio | Fix redirect loop after session expires |
| Changes to the parser | No dice qué cambia ni para qué | Accept trailing commas in the parser |
| Update stuff | No dice nada; el revisor abre el diff a ciegas | Update invoice tax rate to 21% |
| fix: FIX THE THING!!! | Ruido; además el título no se grita | Fix duplicate emails on retry |
| Fix bug where the export job would sometimes time out on big tables. | Larga y con punto final; el porqué va en el cuerpo | Fix export timeout on large tables |
Los verbos que cubren el 90% de los commits son diez, y se usan siempre en la misma forma:
| Verbo | Cuándo | Ejemplo |
|---|---|---|
| Add | Algo que antes no existía | Add retry to the export job |
| Remove | Algo que deja de existir | Remove unused billing helpers |
| Fix | Un comportamiento incorrecto | Fix rounding on discounted items |
| Update | Algo que ya existía cambia de valor o versión | Update Postgres client to 8.13 |
| Rename | Sólo cambia el nombre | Rename Account to Tenant |
| Move | Sólo cambia de lugar | Move date helpers to shared |
| Extract | Sacar una parte a su propia unidad | Extract invoice totals into a service |
| Refactor | Cambia la forma, no el comportamiento | Refactor the checkout flow into steps |
| Handle | Contemplar un caso que faltaba | Handle empty carts at checkout |
| Prevent | Impedir que algo pase | Prevent double submit on slow networks |
Antes de seguir, predecí
El pull request: cinco huecos
Una descripción de pull request tiene un lector concreto: alguien que va a revisar tu código sin saber de dónde salió. Todo lo que escribas tiene que ahorrarle preguntas.
Plantilla
Pull request description
What this does
One or two sentences, in the present tense: "Adds a retry with exponential backoff to the export job."
Presente y en tercera persona: el sujeto es el pull request, no vos. Es la misma frase del título del commit, pero completa.
Why
The problem this solves, with the evidence: "Exports over 10k rows timed out for three customers this week (see #482)."
Acá va el link al issue, al reporte o al gráfico. Un revisor que entiende el problema revisa mucho mejor.
How it works
The approach, and anything non-obvious in the diff: "The job now pages through in chunks of 1000 and resumes from the last page on failure."
Sólo lo que el diff no muestra solo. No narres archivo por archivo: para eso está el diff.
How to test it
Concrete steps or the command to run: "Run `npm run test:export`, or trigger an export on the demo account with 50k rows."
El hueco que más se saltea y el que más tiempo ahorra. Sin esto, el revisor aprueba leyendo, que no es lo mismo que probar.
Notes for the reviewer
Trade-offs, open questions, what you deliberately left out: "The backoff cap is arbitrary at 30s — happy to change it."
Decir en voz alta lo que dudás convierte la revisión en una conversación en vez de una corrección.
| Fórmula | Para qué | Ejemplo |
|---|---|---|
| This PR adds / removes / fixes… | Abrir la descripción | This PR adds pagination to the export job |
| Closes #482 | Cerrar el issue solo al mergear | Closes #482 |
| Follow-up to #479 | Encadenar con trabajo previo | Follow-up to #479, which added the retry |
| Out of scope: … | Frenar el pedido de más cambios | Out of scope: the CSV format itself |
| I went with X over Y because… | Explicar una decisión | I went with polling over websockets because the job runs once a day |
| Open question: … | Pedir opinión sin bloquear | Open question: should the cap be configurable? |
| Draft / ready for review | Decir en qué estado está | Marking this ready for review |
Practicalo
Reescribilo
Una descripción de pull request escrita como un mensaje de chat. Reescribila con los huecos que importan: qué hace, por qué y cómo probarlo.
hi! so this PR is about the export thing that we talked about yesterday, I changed a few files and also fixed a small thing in the date helper that was annoying me. let me know if it looks okAdd pagination to the export job Why: exports over 10k rows timed out for three customers this week (#482). How it works: the job pages through in chunks of 1000 and resumes from the last completed page if a chunk fails. How to test: run `npm run test:export`, or trigger an export on the demo account (52k rows) — it used to time out at 30s. Note: the unrelated date-helper fix moved to #487 to keep this diff focused.
Cada hueco tiene una línea. El saludo y el «let me know if it looks ok» desaparecen: no le dicen nada al revisor. Y el arreglo que no venía al caso se fue a su propio pull request.
Add pagination to the export job Exports over 10k rows timed out (#482). The job now pages through in chunks of 1000. To test: `npm run test:export`.
Para un cambio chico y con un issue que ya explica el problema, tres líneas alcanzan. La plantilla es un piso de preguntas a responder, no un formulario que haya que llenar entero.
Lo importante del segundo modelo: acortar está bien, saltearse el «cómo probarlo» no.
commit
/kəˈmɪt/ · suena como kamít, con acento en la segunda sílaba
Error común: decir «cómit», acentuando la primera
review
/rɪˈvjuː/ · suena como riviú
Error común: decir «rivíu» o «revíu»
draft
/drɑːft/ · suena como draaft, con la a larga
Error común: decir «draf» comiéndose la t
scope
/skəʊp/ · suena como skóup
Error común: decir «escop», con e inicial
squash
/skwɒʃ/ · suena como skuósh
Error común: separar las vocales: «sku-ash»
El audio lo genera tu navegador con voz sintetizada: alcanza para orientarse, y una persona que habla inglés lo dice mejor.
Lo que preguntan sobre esto
En la práctica
Cierre
Autoevaluación
¿Lo entendiste?
Práctica