Git & PR Conventions — Fundamental Playbooks

Nombres de Ramas

Un nombre de rama es documentación viva. Le dice al equipo qué estás haciendo y con qué urgencia, sin abrir el código.

feat/

Nueva funcionalidad

feat/user-auth

fix/

Corrección de bug

fix/login-timeout

chore/

Tareas de mantenimiento, deps

chore/update-eslint

hotfix/

Fix urgente en producción

hotfix/payment-crash

docs/

Documentación

docs/api-auth-endpoints

refactor/

Refactor sin cambio funcional

refactor/extract-payment-gateway

test/

Agregar o corregir tests

test/checkout-e2e

Reglas de naming

Siempre en minúsculas

❌ feat/User-Auth ✅ feat/user-auth

Usá kebab-case, no snake_case

❌ fix/payment_timeout ✅ fix/payment-timeout

Inglés, no español

❌ feat/autenticacion-usuarios ✅ feat/user-authentication

Máximo 3 palabras descriptivas

❌ fix/the-login-form-authentication-token-expiry ✅ fix/auth-token-expiry

Incluí el número de issue si existe

❌ fix/bug ✅ fix/payment-duplicate-#142

Conventional Commits

type(scope): descripción
Un estándar que hace que tu historial de Git sea legible por humanos y por máquinas (changelogs automáticos, semantic versioning).

✨ feat Nueva feature

🐛 fix Bug fix

🔧 chore Mantenimiento, dependencias

📝 docs Solo documentación

♻️ refactor Refactor sin cambio de comportamiento

✅ test Agregar o corregir tests

⚡ perf Mejora de performance

👷 ci CI/CD changes

🎨 style Formato, punto y coma, espacios

Ejemplos buenos y malos

feat(auth): add JWT token refresh logic

Tipo + scope + descripción clara en inglés. Imperativo presente.

✓ Bueno

fix(checkout): prevent double charge on network retry

Explica qué se arregló y bajo qué condición.

✓ Bueno

fix bug

No da contexto. ¿Qué bug? ¿Dónde? Imposible entender en 3 meses.

✗ Malo

WIP

No es un commit, es un grito de auxilio. Squasheá antes de mergear.

✗ Malo

refactor(billing): extract tax calculation to TaxEngine

Refactor + scope + resultado concreto.

✓ Bueno

updated some stuff and fixed things

Vago. Cada palabra genérica es ambigüedad acumulada.

✗ Malo

feat: login

Also fixed the logout bug and updated readme

Tres cosas en un commit. Dividir en commits atómicos.

✗ Malo

perf(api): add Redis cache for product list endpoint

Before: 850ms avg
After: 45ms avg

Body con datos cuantitativos. El reviewer no necesita adivinar el impacto.

✓ Bueno

Reglas de oro:

Imperativo presente: "add", no "added" ni "adding".
Máximo 72 caracteres en la primera línea. Si necesitás más, usá el body.
Un commit = un cambio lógico. Si usás "and" en el mensaje, son dos commits.
El body explica el PORQUÉ y el contexto, no lo que ya dice el diff.

PR Description

Una buena descripción ahorra horas de ida y vuelta. El reviewer debería entender el cambio sin necesidad de preguntar.

Template

### ¿Qué cambia? Resumen en una frase. Si el título del PR ya lo dice, no repitas.

### ¿Por qué? Contexto de negocio o técnico. Link al issue o spec si existe.

### ¿Cómo lo hice? Decisiones técnicas clave. Patrones usados. Alternativas consideradas y descartadas.

### ¿Cómo probarlo? Pasos concretos para QA o reviewer. Comandos, fixtures, seeds, URLs de staging.

### Screenshots / Evidencia Si es UI: antes/después. Si es API: response de curl o Postman.

### Riesgos Qué podría romperse. Migraciones, cambios de schema, dependencias nuevas.

Checklist de PR

¿El título sigue Conventional Commits?

¿El PR tiene una sola responsabilidad (no mezcla refactor + feature + bugfix)?

¿La descripción incluye el PORQUÉ, no solo el QUÉ?

¿Hay instrucciones claras para probar el cambio?

¿Los commits están limpios (no hay "WIP", "fix typo", "try again")?

¿Revertiste cambios de debug (console.log, dump, var_dump)?

¿Corren los tests localmente?

0 / 7 completados

Estrategia de Merge

No hay una estrategia correcta para siempre. La clave es ser consistente y entender el trade-off.

🧹

Squash and merge

Recomendado

Todos los commits de la rama se comprimen en uno solo. El historial de main queda lineal y limpio.

Cuándo: PRs con muchos commits de WIP. Ramas con ida y vuelta. Cuando el viaje no importa, solo el destino.

✅ Historial de main impecable. Un commit = un PR. Fácil revertir.

❌ Pierde el historial granular. No ideal para branches longevas con commits significativos individuales.

🔀

Merge commit

Crea un commit de merge que une la rama a main. Preserva todo el historial de la rama.

Cuándo: Ramas longevas con múltiples features significativas. Cuando cada commit cuenta una parte de la historia.

✅ Preserva el historial completo. Claro qué commits entraron juntos.

❌ Historial de main con ramificaciones. Más ruido visual en git log.

📐

Rebase and merge

Reescribe los commits de la rama sobre la punta de main. Historial lineal sin commits de merge.

Cuándo: Querés historial lineal PERO preservando cada commit individual. Rama con commits atómicos y bien escritos.

✅ Historial lineal. Commits individuales preservados. Sin burbujas de merge.

❌ Reescribe historia (cuidado en ramas compartidas). Más trabajo si hay conflictos.

¿Rebase o Merge? Árbol de decisión

1. ¿Tu rama tiene más de 2 días?

merge rebase

2. ¿Alguien más está trabajando en esta rama?

merge rebase

3. ¿Querés un historial lineal sin merge commits?

rebase merge

4. ¿Los commits individuales de tu rama cuentan una historia útil?

rebase squash

Anti-patrones

git push --force a main o develop

Sobre escribís el historial compartido. Pesadilla para el equipo.

Mergear sin revisar conflictos

El merge commit se crea igual pero puede tener el código roto.

git add . && git commit -m "changes"

Staggeás todo sin discriminar. El mensaje no dice nada. Dos pecados capitales.

Commits directos a main

Saltás code review, CI, y la red de seguridad del equipo.