Disciplina de PRs de Carlos Osuna

Disciplina de PRs

Resumen

Los PRs cuestan tiempo del equipo. La disciplina acá es prevenir el desperdicio (re-revisión por alcance sorprendente, fusión a la rama equivocada, atribución incorrecta) antes que producirlo.

Principio: consenso previo cuando toca arquitectura, formato consistente siempre, destino de fusión verificado dos veces.

Anunciar al inicio: "Aplicando pr-discipline para este PR."

Paso 1: Alinear con el maintainer ANTES de codificar (si aplica)

Enviar un párrafo de propuesta al maintainer del módulo antes de abrir el PR si el cambio toca:

• Forma de respuesta de endpoints existentes.
• Estructura de DTOs o validadores.
• Patrones cross-repo (validadores, servicios, manejo de errores).
• Abstracciones arquitectónicas (decoradores nuevos, capas de servicio, patrones a nivel de módulo).

Plantilla:

"[Maintainer], voy a hacer X para la funcionalidad Y. Alcance: a, b, c. Otros X quedan como están por la razón Z. ¿OK?"

Esperar confirmación. Si hay objeciones, iterar en texto (barato). Si aprueba, el PR pasa sin debate posterior.

No aplica a: correcciones de errores que no cambian contratos, funcionalidades que siguen patrones existentes, refactorizaciones internas a un módulo, documentación o pruebas solas.

Paso 2: Verificar la base correcta del PR

La rama base del PR no siempre es main. Resolverla invocando la skill use-worktrees (Paso 1 — waterfall completo). Una vez resuelta, queda persistida en auto-memoria y futuras invocaciones la toman sin preguntar.

Flujos comunes que esta skill respeta:

Flujo	Rama de funcionalidad parte de	PR apunta a
Backend con búfer de staging	staging	staging (después staging → main aparte)
Móvil / web simple	main o main-web	main o main-web
Gitflow tradicional	dev	dev (después dev → master)
Trunk-based	main o trunk	main o trunk

No asumir; resolver siempre.

Paso 3: Reutilizar antes que crear

Antes de añadir cualquier archivo, validador, guarda, servicio, componente, helper, constante o tipo nuevo: invocar la skill reuse-existing-patterns. Esa skill cubre cómo buscar (por categoría), cuándo usar lo existente y cuándo es legítimo crear un paralelo (con justificación en el cuerpo del PR).

No empezar a codificar sin haber pasado por ese reflejo — es el motivo número uno de comentarios de revisión del tipo "esto ya existe, usa el patrón actual".

Paso 4: Crear el PR — título, cuerpo, atribución

Título

• Menos de 70 caracteres. Lo largo va al cuerpo.
• Formato del repositorio (Conventional Commits si está; si no, frase corta).
• En el idioma del equipo (si el equipo escribe en español, el título va en español).

Cuerpo

Plantilla mínima:

## Resumen
<1-3 viñetas de QUÉ cambia y POR QUÉ>

## Plan de pruebas
- [ ] <comando o flujo a verificar>
- [ ] <otro>

## Riesgo
<casos límite, plan de reversión, dependencias>

Si el repositorio tiene plantilla (.github/PULL_REQUEST_TEMPLATE.md), usarla como base.

Atribución (identidad del commit)

Nunca pasar -c user.email=... ni -c user.name=... a git commit. El repositorio del trabajo tiene configuración local correcta; el global suele ser personal. Sobrescribir accidentalmente atribuye commits del trabajo a la cuenta personal de GitHub.

Verificar antes de enviar (push):

git log -1 --format='%an <%ae>'

Si el email no es el del trabajo, no enviar — corregir antes:

git commit --amend --reset-author   # usa la configuración local actual

No reescribir historia de main/staging (ramas protegidas) solo por atribución — el costo del force-push supera el beneficio.

Paso 5: Subir markdown con backticks limpios

gh pr edit --body-file y gh pr comment --body escapan los backticks a \``, rompiendo el formato. Solución: gh api -X PATCH` con payload JSON.

python3 <<'PY'
import json, subprocess
with open('/tmp/body.md') as f:
    body = f.read()
subprocess.run(
    ['gh', 'api', '-X', 'PATCH', 'repos/<org>/<repo>/pulls/<num>', '--input', '-'],
    input=json.dumps({'body': body}), text=True, check=True
)
PY

Verificar:

gh pr view <num> --json body --jq .body | head -10

Si los backticks salen literales (no escapados), está limpio.

Paso 6: Estilo de comentarios de revisión

• Agrupar por severidad: Bloqueante / Mejoras menores / Nits.
• Una viñeta por hallazgo, en una línea: qué + por qué + corrección sugerida.
• Formato archivo.ts:42 para referenciar líneas (clicable en GitHub).
• Comenzar con la razón antes que con la observación. Como notas al margen de un compañero, no como auditoría externa.
• Si el autor documentó su razonamiento en el cuerpo del PR, involucrarse con ese razonamiento — no reinventarlo desde primeros principios.
• Sin etiquetas artificiales tipo "B1", "M2". Sin bloques de código de ejemplo cuando no aportan.

Lo que un revisor humano experimentado nota como "AI dump": estructura demasiado simétrica, mismas frases de transición, viñetas sin contexto del autor.

Paso 7: Fusionar — squash vs merge según el flujo del equipo

Verificar la convención del repositorio. Patrones comunes:

Tipo de repositorio	funcionalidad → integración	integración → main
Backend con staging	squash	merge commit
Móvil/web sin staging	squash o merge	N/A
Gitflow tradicional	merge a dev	merge a master

Por qué la asimetría en repositorios con staging: si haces squash de staging → main, el PR parece gigante (repite N funcionalidades ya squasheadas). El merge commit preserva la lista de funcionalidades tal como cayeron en staging.

# funcionalidad → staging
gh pr merge --squash <num>

# staging → main (en repositorios que separan)
gh pr merge --merge <num>

NUNCA fusionar directamente a main si el repositorio tiene staging:

• git revert deshace el código pero los commits quedan en la historia para siempre — visibles para todo el equipo.
• Verificar tres veces el --base de gh pr create y el destino de la fusión en la interfaz de GitHub antes de presionar.
• Preguntarle al usuario "¿fusiono a staging?" antes de ejecutar gh pr merge si hay duda.

Referencia Rápida

Situación	Acción
Cambio toca contratos o arquitectura	Paso 1: alinear con maintainer
Crear rama	Paso 2: resolver base con waterfall
Empezar implementación	Paso 3: buscar si el patrón ya existe en el repositorio
Listo para abrir PR	Paso 4: título <70, cuerpo con plantilla, verificar atribución
Cuerpo o comentario con código	Paso 5: gh api PATCH con JSON
Dejar revisión	Paso 6: viñetas por severidad, comenzar con razón
Fusionar	Paso 7: squash vs merge según convención
Repositorio con staging	NUNCA fusionar directamente a main

Errores Comunes

• Abrir PR arquitectónico sin pre-alineación. Produce 2-3 rondas de re-revisión y debate posterior. Enviar el párrafo de propuesta antes de codificar.
• Crear archivo o abstracción nueva cuando ya existe equivalente. Buscar primero (Paso 3). El revisor va a señalarlo.
• Título > 70 caracteres con la descripción completa. Título corto, el detalle va al cuerpo.
• Pasar -c user.email para commits scriptados. Sobrescribe la configuración local del trabajo con la global personal.
• gh pr edit --body-file file.md con backticks. Los escapa. Usar gh api PATCH con JSON.
• Revisiones en prosa narrativa. El usuario quiere viñetas por severidad — escaneable, no narrativa.
• Squash de staging → main. Repite historia que ya fue squasheada en cada funcionalidad. Usar merge commit.
• Fusionar directamente a main "porque es pequeño". Los commits quedan en la historia para siempre, visibles para todos.

Banderas Rojas

Nunca:

• Abrir PR que toca contratos/arquitectura sin alineación previa.
• Crear archivo o abstracción paralela cuando ya existe equivalente.
• Pasar -c user.email / -c user.name a git commit.
• Enviar (push) sin verificar git log -1 --format='%ae'.
• Usar gh pr edit --body-file para markdown con backticks.
• Fusionar directamente a main en repositorio con staging.
• Hacer squash de staging → main.
• Dejar revisión sin agrupar por severidad.

Siempre:

• Pre-alinear cambios arquitectónicos con el maintainer.
• Resolver la base del PR con el waterfall, no asumir main.
• Buscar si el patrón ya existe en el repositorio antes de crear uno nuevo.
• Título <70 + cuerpo con Resumen + Plan de pruebas + Riesgo.
• Verificar atribución del commit antes del push.
• gh api PATCH con JSON para markdown con código.
• Viñetas por severidad en revisiones, comenzar con razón.
• Squash en funcionalidad → integración, merge commit en integración → main.