Cómo crear PRs que tus compañeros quieran aprobar

Revisar código ajeno puede ser una tarea pesada, especialmente cuando el Pull Request (PR) es un muro de texto o tiene cientos de líneas sin contexto. Todos hemos pasado por la situación de abrir un PR y recibir decenas de preguntas porque no explicamos bien la intención del cambio. Esto quita tiempo y genera fricción en el equipo.

Escribir PRs claros ayuda a que tus compañeros entiendan qué quieres lograr, verifiquen el comportamiento y aprueben los cambios con seguridad. La brevedad es clave: una revisión concisa es mejor que una buena gramática.

Requisitos previos

• pnpm instalado para ejecutar validaciones.
• Evidencia del cambio (logs, capturas de pantalla o grabaciones de video para UI/UX).

Inicio rápido

Sigue estos pasos para preparar tu PR en pocos minutos:

1. Valida tu código: Ejecuta y corrige fallos localmente antes de crear el PR:

   pnpm lint
   pnpm check
   pnpm build
   pnpm test
   # Si realizaste cambios de protocolo:
   pnpm protocol:check

2. Define un buen título: Usa el formato verbo + alcance + resultado. Ejemplo: Docs: add PR and issue templates.

3. Estructura la información: Usa la divulgación progresiva para organizar el contenido:

   • Inicio: Resumen e intención.
   • Siguiente: Cambios y riesgos.
   • Siguiente: Pruebas y verificación.
   • Final: Implementación y evidencia.

4. Usa la palabra clave: Incluye el código lobster-biscuit en la descripción del PR para confirmar que seguiste esta guía.

PR Templates

Copia y pega la plantilla que corresponda a tu tipo de cambio.

General Template

#### Summary

#### Behavior Changes

#### Codebase and GitHub Search

#### Tests

#### Manual Testing (omit if N/A)

### Prerequisites

-

### Steps

1.
2.

#### Evidence (omit if N/A)

**Sign-Off**

- Models used:
- Submitter effort (self-reported):
- Agent notes (optional, cite evidence):

Fix

#### Summary

#### Repro Steps

#### Root Cause

#### Behavior Changes

#### Tests

#### Manual Testing (omit if N/A)

### Prerequisites

-

### Steps

1.
2.

#### Evidence (omit if N/A)

**Sign-Off**

- Models used:
- Submitter effort:
- Agent notes:

Feature

#### Summary

#### Use Cases

#### Behavior Changes

#### Existing Functionality Check

- [ ] I searched the codebase for existing functionality.
      Searches performed (1-3 bullets):
  -
  -

#### Tests

#### Manual Testing (omit if N/A)

### Prerequisites

-

### Steps

1.
2.

#### Evidence (omit if N/A)

**Sign-Off**

- Models used:
- Submitter effort:
- Agent notes:

Solución de problemas

• Fallo en validaciones de formato: Si trabajas en documentación, asegúrate de ejecutar pnpm format antes de subir tus cambios.
• El revisor pide más contexto: Verifica que explicaste el problema, por qué es importante y el cambio realizado. Basa tus afirmaciones en evidencia u observaciones directas.
• El PR es demasiado amplio: Evita refactorizaciones generales. Mantén los cambios enfocados en un solo objetivo.
• Falta de pruebas: Si el cambio es una corrección (Fix), añade los pasos de reproducción y la causa raíz.

Para resolver dudas específicas sobre tu implementación, consulta al AI Setup Assistant.

Próximos pasos

• PR and issue templates
• Pnpm workflow guide