Por qué importa el título del PR
El título del PR es lo que ven los reviewers en su lista, lo que aparece en notificaciones y -si usás squash merge- lo que termina como mensaje del commit en main. Un buen título ahorra clicks (no hace falta abrir el PR para entender de qué va) y facilita la búsqueda seis meses después.
Estructura recomendada
<tipo>(<scope>): <verbo en imperativo> <qué cambia>.
Ejemplos: feat(auth): add password reset flow,
fix(api): handle null response from upstream,
refactor(billing): extract invoice generator into service.
Verbos en imperativo
"Add", "fix", "refactor", "remove", "update", "improve", "rename", "extract", "bump". El gerundio ("adding") y el pasado ("added") son menos directos. La regla mnemónica vale para PR titles también: "If applied, this PR will add password reset flow".
Qué evitar
- "Misc fixes" o "Update stuff": no informan nada.
- Titles con el número del ticket sólo:
PROJ-123sin descripción. - WIP en el título cuando ya está listo para review.
- Emojis al inicio si tu repo usa squash merge: rompen herramientas de parsing.
- Más de 72 caracteres: se trunca en muchas vistas.
Squash merge y commit message
Con squash merge, el título del PR se convierte en el mensaje del commit en main. Si seguís Conventional Commits en los títulos, semantic-release puede armar changelogs automáticamente. Si en cambio hacés merge commit, los commits originales se conservan y el título del PR es solo metadata.
El cuerpo del PR
El título dice qué; el body dice por qué. Plantilla típica: What (resumen en una frase), Why (motivación), How (decisiones técnicas), Testing (cómo verificaste), Screenshots (si aplica), Related (links a issues, docs).
Tickets y referencias
Si usás un sistema con magic words (Closes #123, Fixes JIRA-456),
ponelos en el body, no en el título. GitHub y GitLab cierran issues automáticamente al
mergear. La excepción: incluir el ID del ticket si tu repo así lo exige por política.
PRs grandes vs chicos
Si el título no entra en 72 caracteres, probablemente el PR es demasiado grande. Dividilo en PRs más chicos con títulos específicos. Reviews de PRs gigantes son superficiales y atrasan al equipo. La meta razonable: PRs que se revisen en 15 minutos o menos.