Ingles para pull requests y code reviews: la guia para devs

Si trabajas en un equipo de desarrollo que opera en ingles, gran parte de tu comunicacion escrita no pasa por Slack ni por email: pasa por GitHub, GitLab o Bitbucket. Pull requests, code reviews, issue comments, commit messages.

Y ahi es donde muchos devs latinoamericanos tienen un gap inesperado. No es que no entiendan el codigo - es que no saben como describir lo que hicieron, como dejar comentarios que suenen constructivos en vez de criticos, o como responder al feedback sin sonar defensivo.

Esta guia cubre exactamente eso.

Como escribir una PR description que la gente realmente lea

Una buena PR description no es opcional: es lo que hace la diferencia entre una revision rapida y dias de ida y vuelta de preguntas.

La estructura basica

La mayoria de los repos open source maduros tiene un template de PR. Si el tuyo no lo tiene, esta estructura funciona en casi todos los contextos:

## What changed
[Descripcion breve de los cambios - 1 a 3 oraciones]

## Why
[Contexto: por que era necesario este cambio]

## How to test
[Pasos para que el reviewer reproduzca y verifique el cambio]

## Screenshots (si aplica)
[Para cambios de UI, antes/despues]

## Notes
[Anything the reviewer should know: breaking changes, dependencies, known limitations]

Ejemplos reales

Malo (demasiado vago):

Fixed the bug with the login form.

Bueno:

What changed: Fixed a race condition in the login form where rapid form submissions could trigger multiple auth requests, causing intermittent 401 errors.

Why: Users were reporting that clicking "Sign in" quickly twice sometimes resulted in a logout right after login. The root cause was that both requests would succeed but the second one would overwrite the session token.

How to test: 1. Go to /login. 2. Enter valid credentials. 3. Double-click "Sign in" quickly. 4. Confirm you land on the dashboard without being redirected back to login.

Notes: Added debounce of 300ms to the submit button. This is consistent with how we handle other forms in the codebase (see src/components/ContactForm).

Verbos de accion que muestran precision

Los mejores devs usan verbos especificos que comunican exactamente que tipo de cambio hicieron:

En vez de	Usa
changed X	refactored X to improve readability
fixed bug	resolved race condition in X
updated function	extracted validateInput into a shared utility
deleted old code	removed deprecated legacyAuth module
moved code	migrated auth logic from utils.ts to auth/ module
added X	introduced rate limiting to prevent brute-force attacks
rewrote X	replaced custom date parser with date-fns to reduce maintenance burden

Mas verbos utiles: optimized, simplified, consolidated, separated, aligned, enforced, wired, stubbed, mocked, deprecated, superseded, documented, exposed, abstracted, normalized, sanitized.

Como escribir comentarios de code review

Los comentarios de code review son probablemente la forma de comunicacion tecnica escrita que mas tension puede generar en un equipo. Un comentario mal redactado puede hacer que el otro dev se sienta atacado, aunque la intencion haya sido totalmente constructiva.

Los tipos de comentarios y como etiquetarlos

Un patron muy usado en equipos maduros (popularizado en parte por repos como el de Google y empresas como Netlify) es etiquetar los comentarios por tipo:

• nit: Un detalle menor de estilo o preferencia, no bloqueante. "nit: prefer const over let here since it's not reassigned"
• suggestion: Una mejora que vale la pena considerar, pero la decision es del autor. "suggestion: this could be simplified using Array.from()"
• question: Genuinamente no entiendes algo y queres que te expliquen. "question: why is this called before the auth check? Is there a specific reason?"
• issue: Un problema real que necesita ser resuelto antes de mergear. "issue: this will throw if user is null - need to handle that case"
• blocker: Un problema critico que no puede ir a produccion. "blocker: this query has O(n) complexity and will time out with large datasets"

Cuando no etiquetas, el autor no sabe si su codigo esta bien o si hay que cambiarlo. La etiqueta reduce el trabajo interpretativo del otro lado.

Ejemplos de comentarios segun tono

Demasiado directo (puede sonar agresivo):

This is wrong. You need to handle the null case.

Pasivo-agresivo:

As I mentioned in my last review, we need to handle null cases here.

Pedante (innecesariamente largo):

According to the JavaScript specification, when you access a property of undefined, it throws a TypeError. This is a well-known issue and has been documented extensively. You should consider adding a null check here as per best practices established in our coding guidelines document section 3.2.

Constructivo y especifico:

issue: user.profile will throw a TypeError if user is null. This can happen when the session expires mid-request. Consider:

const profile = user?.profile ?? defaultProfile;

Or add an early return if user is required for this flow.

Con pregunta en vez de afirmacion:

question: could this throw if items is empty? I'm thinking about the items[0] access on line 47.

Frases utiles para comentarios de review

Para sugerencias no bloqueantes:

• "This works, though you might also consider..."
• "Not a blocker, but..."
• "Optional: feel free to ignore, just thinking out loud..."
• "Might be worth extracting this into a separate function for reuse..."

Para hacer preguntas:

• "Can you help me understand why...?"
• "What's the reasoning behind...?"
• "Is this intentional or...?"
• "I might be missing context, but..."

Para aprobar con comentarios:

• "LGTM (looks good to me) - just a couple of nits below, feel free to address or ignore"
• "Approved - one minor suggestion inline"

Para pedir cambios con respeto:

• "Before we merge, could you..."
• "I'd feel more comfortable merging this if we..."
• "This is mostly great - one thing I'd like to address first..."

Como responder al feedback sin sonar defensivo

Recibir feedback en un code review es incómodo en cualquier idioma. En ingles hay algunos patrones que ayudan a que la conversacion sea productiva:

Aceptar y resolver

Cuando el feedback tiene razon:

• "Good catch, fixing this now."
• "You're right - I missed that case. Updated."
• "Done, thanks for the sharp eye."
• "Fixed in the latest commit."

Evitar la tentacion de justificar el error. "I was tired when I wrote this" no agrega valor al review.

Explicar sin justificar

Cuando tenes razon vos:

• "This is intentional - [explicacion breve]. Happy to add a comment if that would help."
• "I considered that approach, but went with this because [razon]. Let me know if you think the trade-off is worth it."
• "This follows the pattern we established in [archivo de referencia] - does that context help?"

Cuando no estas de acuerdo

• "I see your point - I'm not sure I agree, though. My concern with that approach is..."
• "I hear you. Could we discuss this async before I make the change? I want to make sure we're aligned on the direction."
• "This might be a preference thing - both approaches work. Should we add it to the team discussion?"

Cuando no entendiste el comentario

• "Could you clarify what you mean by [X]? I want to make sure I understand the concern before making changes."
• "I'm not sure I follow - are you suggesting [interpretacion A] or [interpretacion B]?"

Commit messages: el formato que habla de tu nivel de senioridad

Los commit messages son comunicacion con tu yo del futuro y con todo el equipo. El formato mas aceptado en la industria es el Conventional Commits:

<type>(<scope>): <description>

[optional body]

[optional footer]

Tipos mas comunes:

• feat: nueva funcionalidad
• fix: bug fix
• refactor: cambio de codigo que no agrega feature ni arregla bug
• docs: cambios en documentacion
• test: agregar o corregir tests
• chore: cambios de build, CI, dependencias
• perf: mejora de performance
• style: formateo, punto y coma, etc. (no cambia logica)

Ejemplos:

Malo:

fixed stuff

Malo:

WIP

Bueno:

fix(auth): resolve race condition in concurrent login requests

When users submitted the login form twice quickly, both requests
would succeed but the second token would overwrite the first,
causing immediate logout.

Added 300ms debounce to submit handler.
Closes #234

Bueno (mas corto, para cambios simples):

feat(billing): add invoice download button to subscription page

Reglas de oro:

• Usar tiempo presente imperativo: "add" no "added", "fix" no "fixed". Pensar en: "Si aplico este commit, va a X."
• La primera linea: maximo 72 caracteres
• El body explica el por que, no el que (el diff ya muestra el que)

Ejemplo de un PR de open source para estudiar

Vale la pena leer PRs de repos open source maduros para ver el idioma en accion. Algunos que tienen muy buena cultura de PR:

• Next.js (vercel/next.js): descripciones claras con contexto de performance y breaking changes
• React (facebook/react): discusiones largas pero muy bien articuladas
• Tailwind CSS (tailwindlabs/tailwindcss): PRs muy concisos y bien estructurados
• tRPC (trpc/trpc): buena cultura de "nit" y comentarios etiquetados

Leer los comentarios de maintainers en estos repos es una forma gratuita de aprender el ingles tecnico en contexto real.

Glosario de abreviaciones que vas a ver en reviews

Abreviacion	Significado
LGTM	Looks good to me (aprobado)
nit	Nitpick (detalle menor)
WIP	Work in progress (no listo para mergear)
RFC	Request for comments (pedido de feedback, no listo)
IMO	In my opinion
IIRC	If I recall correctly
FWIW	For what it's worth
TBH	To be honest
AFAIK	As far as I know
ACK	Acknowledged (entendido, de acuerdo)
NACK	Not acknowledged (en desacuerdo, para protocolo de consenso)

Conclusion

La comunicacion escrita en GitHub es una habilidad que se desarrolla con practica deliberada. No es suficiente con saber ingles general: hay patrones especificos de como los equipos tecnicos se comunican en este medio.

Lo mas importante: ser claro y especifico. Una PR description vaga o un comentario de review ambiguo genera trabajo extra para todos. La precision en el lenguaje es una forma de respeto por el tiempo de los demas.

Si queres practicar este tipo de ingles tecnico en un entorno donde podes cometer errores sin consecuencias, hace el diagnostico gratuito de Gringuear. El chat de IA esta disenado para contextos laborales reales y puede ayudarte a pulir exactamente este tipo de comunicacion escrita.