DEV Community: Fernando Gallardo

How to write a good pull request description

Fernando Gallardo — Thu, 18 Jun 2026 16:00:00 +0000

A pull request without a description is a puzzle with missing pieces.

The reviewer has to reconstruct what you were trying to do, why you did it this way, and what could go wrong, from the code alone. That’s not a review, it’s archaeology. And it’s why so many PRs get approved with a “LGTM” that doesn’t mean anything.

A good PR description isn’t bureaucracy. It’s the thing that makes your change reviewable — and therefore mergeable — without three rounds of back-and-forth.

Why most PR descriptions fail

The most common PR descriptions look like this:

”Fix bug”
”Update user service”
”WIP”
”Changes per feedback”

These tell the reviewer nothing. They don’t explain what the bug was, what broke, what the fix does, or how to verify it works. The reviewer is starting from zero.

The second most common failure is the opposite: a description that’s just a list of every file changed, copy-pasted from the diff. That’s also useless, it describes what changed, not why.

A good description answers the questions a reviewer would ask if they could.

The goal is to make the review faster and the approval more confident.

What to include in a pull request

A PR description that actually helps has four components. None of them are long, a good description for a focused PR can be under 150 words. The point is structure, not volume.

1. What this change does (2-4 sentences)

Not a list of files. Not a commit log. A plain explanation of what problem this PR solves and what it does to solve it.

This PR adds rate limiting to the /auth/login endpoint. Witout it, the endpoint can be used for credential stuffing with no hrottling. The implementation uses a sliding window counter in Redis with a 60-second TTL.

2. Why this approach

If there were alternative implementations you considered and rejected, say so.

This prevents reviewers from suggesting alternatives you already evaluated, and it shows your reasoning.

We considered using an in-memory counter, but that doesn’t work across multiple instances. Redis was already in the stack, so the overhead is minimal.

3. How to test it

Specific steps. Not “run the tests”, which tests? Where? Under what conditions?

Start the service locally with docker compose up

Hit /auth/login more than 10 times in 60 seconds with any credentials

The 11th request should return 429

4. What’s out of scope

This one gets skipped most often, but it prevents the review from expanding into territory you didn’t intend to cover.

This PR doesn’t address rate limiting on other endpoints. that’s tracked in #412.

Pull request best practices for developers

Beyond the description itself, there are a few pull request best practices that consistently improve review quality:

Keep PRs focused. A PR that does one thing is easier to review than one that does three. If you’re fixing a bug and refactoring a module and updating a dependency, that’s three PRs, or at minimum, a description that clearly separates the three concerns.

Link to the issue or ticket. The PR description doesn’t need to contain all the context, it needs to point to where the context lives. A link to the relevant issue, Jira ticket, or design doc is worth more than a paragraph trying to summarize it.

Don’t self-review your own PR right after writing it. The gap between writing code and reviewing it needs to be longer than five minutes. Come back to it after a break, or ask for a review first and do your own pass after seeing the comments.

Add a screenshot or recording for UI changes. A reviewer who can see the before/after state will spot visual regressions that are invisible in a diff.

The security section most teams skip

There’s one section most PR templates don’t include: a note on security implications.

Not every PR needs this, a typo fix doesn’t. But any PR that touches authentication, authorization, input handling, file uploads, external APIs, or new dependencies should include a line or two about what the security surface is and how it’s handled.

This doesn’t need to be a formal threat model. It can be as simple as:

Security: This endpoint accepts file uploads. Files are validated for MIME type and size limit before being written to S3. No user-supplied file path is used.

Or:

Dependencies: Added jsonwebtoken@9.0.2. Checked against OSV, no known CVEs. Replaces the unmaintained jwt-simple package.

Teams that use automated security analysis in CI can use that output as a reference, if the scanner flagged something, the PR description should acknowledge it and explain how it was resolved. Platforms like Ixtli produce per-PR security summaries that make this easy to include without doing the research manually.

A template you can actually use

Here’s a minimal template that covers the essentials. Adapt it to your team’s conventions, the point isn’t to fill out every field for every PR, it’s to make the important fields habitual.

GitHub

## What

[1-3 sentences: what problem does this solve and how]

## Why this approach

[Optional: alternatives considered and why they were rejected]

## How to test

[Specific steps to verify the change works]

## Out of scope

[What this PR explicitly doesn't cover]

## Security notes

[Optional: relevant security surface, how it's handled, or "no security impact — [reason]"]

Keep it in a .github/pull_request_template.md file and GitHub will auto-populate it for every PR.

GitLab

Keep it in a .gitlab/merge_request_templates/Default.md

Example

my-project/
├── .gitlab/
│   └── merge_request_templates/
│       └── Default.md
├── src/
└── README.md

## What

Describe the change and the problem it solves.

## Why

Why was this implementation chosen?

## How to test

Steps to verify the change works.

## Risks

Potential side effects or areas that may be impacted.

## Security impact

- [ ] No security impact
- [ ] Authentication / Authorization
- [ ] Input validation
- [ ] Secrets / Credentials
- [ ] Data exposure
- [ ] Infrastructure / Configuration

Conclusion

A PR description is not documentation for posterity. It’s communication for the reviewer who has to understand your change in the next 20 minutes.

The investment is small — 10 to 15 minutes to write a description that gives your reviewer everything they need. The return is a review that’s faster, more accurate, and less likely to require three rounds of clarification.

If your team’s PRs consistently lack context, the easiest fix is a template in the repo. Add it this week. If you want to take the security side further

without making it a manual process, ixtli.app integrates directly into the PR workflow.

Cómo hacer una buena revisión de código

Fernando Gallardo — Thu, 18 Jun 2026 03:08:01 +0000

Revisar código es una de las actividades más subestimadas del desarrollo de software.

La mayoría de los equipos la tratan como un trámite, algo que hay que aprobar antes de mergear. El resultado es que los PRs se aprueban con un “LGTM” después de dos minutos de scroll, y los problemas reales pasan de largo.

Una revisión bien hecha no es leer línea por línea buscando typos. Es entender qué intenta hacer ese código, si lo hace de la manera correcta, y si introduce riesgos que no existían antes. Eso requiere un proceso, no un instinto.

Este artículo cubre cómo estructurar ese proceso: qué revisar, en qué orden, qué preguntas hacer, y cómo detectar problemas de seguridad sin ser un experto en ciberseguridad.

Empieza por el contexto, no por el código

El error más común en code review es abrir el diff y empezar a leer desde la primera línea modificada. Antes de ver una sola línea, necesitas entender qué problema resuelve este cambio.

Lee la descripción del PR. Si no hay descripción, o si dice “fixes bug”, ya encontraste el primer problema. Un PR sin contexto obliga al reviewer a reconstruir el razonamiento del autor desde cero, y eso aumenta la probabilidad de aprobar algo que no debería aprobarse.

Lo que un buen PR debe explicar:

Qué cambia no cómo, sino qué problema resuelve
Por qué este approach si hay alternativas que se descartaron, decirlo
Cómo probarlo, pasos para verificar que funciona
Qué no cubre, scope explícito evita confusiones

Si tienes esa información antes de ver el diff, tu revisión va a ser significativamente más efectiva.

Qué revisar y en qué orden

No toda línea de código merece el mismo nivel de atención. Un buen reviewer distribuye su energía de forma inteligente.

Primero: arquitectura y flujo de datos. ¿El cambio tiene sentido a nivel de diseño? ¿Agrega una dependencia innecesaria? ¿Rompe alguna abstracción existente? Esto es lo más difícil de cambiar después.

Segundo: lógica de negocio. ¿El código hace lo que dice que hace? ¿Los edge cases están cubiertos? ¿Qué pasa si el input viene vacío, nulo, o malformado?

Tercero: seguridad. Este punto merece su propia sección.

Cuarto: legibilidad y convenciones. Nombres de variables, estructura de funciones, comentarios. Importante, pero no el punto de partida.

La mayoría de los reviewers hacen esto al revés, empiezan por los detalles de estilo y llegan agotados a lo que realmente importa.

Cómo detectar problemas de seguridad en code review

Detectar vulnerabilidades durante un code review no requiere ser un especialista en seguridad. Requiere hacerse las preguntas correctas.

Hay patrones que aparecen consistentemente en PRs problemáticos:

Entradas sin validar. ¿Los datos que vienen del exterior (usuario, API, archivo) se usan directamente sin sanitizar? Cualquier lugar donde un string externo toca una query, un path de archivo, o una llamada a sistema es candidato a revisión.

Manejo de errores que expone información. Stack traces devueltos al cliente, mensajes de error con rutas internas, logs que incluyen tokens o passwords. Esto pasa más de lo que parece.

Dependencias nuevas. Cada npm install o pip install que aparec en el diff es una superficie de ataque potencial. ¿Se revisó el paquete? ¿Tiene CVE conocidos? ¿Cuántos mantenedores activos tiene?

Secrets hardcodeados. Claves API, tokens, URLs de bases de datos. Son más comunes de lo que cualquier equipo quiere admitir.

Algunos equipos integran análisis automatizado directamente en el flujo de revisión para que estos patrones se marquen antes de que el reviewer los vea. Herramientas como Ixtli, por ejemplo, analizan el diff completo del PR contra el grafo de dependencias del proyecto, no solo las líneas cambiadas, lo que hace que ciertos tipos de vulnerabilidades sean mucho más difíciles de pasar por alto.

Cómo dar feedback que sirva

El objetivo de un comentario en un code review no es demostrar que encontraste algo malo. Es que el código mejore.

Algunas reglas que hacen una diferencia real:

Sé específico. “Este código es confuso” no ayuda. “Esta función hace tres cosas distintas, considera extraer la lógica de validación a una función separada” sí ayuda.

Distingue entre bloqueante y sugerencia. No todo comentario debe impedir el merge.

Prefija con [bloqueante], [sugerencia] o [nitpick] para que el autor sepa qué es crítico y qué es opcional.

Pregunta antes de asumir. Si algo no se entiende, pregunta. “¿Por qué se usa setTimeout aquí en lugar de un event listener?” es mejor que asumir que es un error.

Aprueba cuando está listo. No sigas agregando comentarios menores una vez que los problemas reales están resueltos. El proceso de review también tiene un costo.

Checklist para code review

Antes de aprobar un PR, recorre estos puntos:

| Área | Pregunta |

|------|---------|

| Contexto | ¿El PR tiene descripción clara de qué resuelve? |

| Diseño | ¿El cambio tiene sentido arquitectónico? |

| Lógica | ¿Los edge cases están cubiertos? |

| Seguridad | ¿Hay entradas sin validar, secretos expuestos, o dependencias nuevas sin revisar? |

| Tests | ¿Los tests cubren los casos relevantes, no solo el happy path? |

| Deuda técnica | ¿El cambio deja el código en mejor estado del que lo encontró? |

No es una lista para leer rápido. Es una lista para detenerse en cada punto.

Conclusión

Una buena revisión de código no es más lenta que una mala, es más intencional.

La diferencia está en saber qué buscar y en qué orden.

Si tu equipo trata los PRs como trámites, el problema no es el código, es el proceso.

Empezar a usar un checklist consistente, pedir descripciones reales en cada PR, y separar los comentarios bloqueantes de las sugerencias son cambios que se pueden implementar esta semana sin herramientas adicionales.

Para la parte de seguridad, revisar manualmente cada dependencia nueva o cada input sin validar es costoso en tiempo. Vale la pena evaluar qué parte de ese trabajo puede automatizarse, ixtli.app está construido específicamente para ese slice del proceso.