Escribir buenos PRs y READMEs

Por que es importante la escritura tecnica

En la revision de codigo, la descripcion de su PR es el punto de entrada del revisor. Una buena descripcion de PR puede:

Permitir que el revisor entienda rapidamente lo que hizo
Reducir las preguntas de ida y vuelta
Mostrar que usted piensa cuidadosamente
Ahorrarle tiempo cuando revise el historial 3 meses despues

De la misma manera, un buen README puede:

Permitir que los nuevos integrantes se pongan al dia rapidamente
Reducir preguntas repetitivas
Hacer que el proyecto luzca profesional

Estructura estandar de descripcion de PR: What/Why/How/Testing

1. What (que se hizo)

Resumen conciso, una oracion.

Refactor authentication flow to support OAuth2 and magic link sign-up

Expresiones clave:

Add X — Nueva funcionalidad (no existia antes): “Add OAuth2 support”
Fix X — Correccion de bug: “Fix race condition in cache”
Refactor X — Reescritura de codigo (sin cambiar funcionalidad): “Refactor auth middleware”
Optimize X — Mejora de rendimiento: “Optimize query performance”
Implement X — Implementar un diseno: “Implement the design from #123”

2. Why (por que se hizo)

Esta es la parte que se omite con mas frecuencia. Explique el contexto y la motivacion.

Why:
- Users requested passwordless sign-up option
- Current session-based auth doesn't scale to multiple domains
- OAuth2 is industry standard for enterprise integrations

Indicadores de un buen Why:

Menciona la razon de negocio (necesidad del usuario, rendimiento, mantenibilidad)
Explica por que la solucion actual no es suficiente
Explica por que esta solucion es mejor

3. How (como se hizo)

Vision general de alto nivel de la implementacion tecnica. No necesita explicar linea por linea (eso es trabajo de la revision de codigo), pero el revisor necesita conocer la arquitectura general.

How:
1. Created JWT service using Web Crypto API for signing/verification
2. Replaced SessionMiddleware with AuthMiddleware that validates JWT
3. Added OAuth2 routes for Google/GitHub sign-in
4. Migrated user session storage from cookie to JWT claims
5. Added magic link generation and validation

Breaking changes:
- Moved user auth state from server session to JWT (stateless)
- Clients now need to store and send JWT in Authorization header

4. Testing (como se probo)

Explique como verifico que este cambio es correcto.

Testing:
- Manual testing: Verified OAuth2 sign-in with Google and GitHub accounts
- Verified JWT expiration and refresh flow works correctly
- Existing auth tests pass (147 tests)
- Added 23 new tests for JWT and OAuth2 flows
- Load tested with 1000 concurrent requests (no issues)
- Tested on staging environment with real data

Plantilla de descripcion de PR

Copie esto y llene los espacios:

## What
[Resumen en una oracion]

[Descripcion mas detallada, 2-3 oraciones]

## Why
- [Razon 1]
- [Razon 2]
- [Razon 3, si aplica]

## How
1. [Cambio 1]
2. [Cambio 2]
3. [Cambio 3]

[Si hay breaking changes, indiquelos aqui]

## Testing
- [Que pruebas hizo]
- [Cuales fueron los resultados]
- [Partes pendientes (si las hay)]

## Related
Closes #123
Depends on #456 (wait for this to merge first)

Trampas gramaticales de la escritura tecnica

1. Tiempo verbal (el error mas comun)

Principio: Presente para lo que hace el codigo, pasado para los cambios que usted hizo

Error	Causa	Correcto
”The function was created to handle X”	Suena como narrativa historica	”The function handles X” o “This PR adds a function that handles X"
"The code will validate input”	Demasiado incierto	”The code validates input"
"We added the feature” (en README)	El README no narra historia	”This feature allows users to…“

2. Articulos (error comun para hispanohablantes)

Principio: La primera vez use “a/an”, despues use “the”; o use plural para evitar articulos

Error	Causa	Correcto
”We refactored authentication flow”	No queda claro cual flow	”We refactored the authentication flow"
"Function handles case when user logs in”	Falta “the"	"The function handles the case when a user logs in”

3. Exceso de voz pasiva

Principio: El ingles prefiere la voz activa. A menos que no quiera decir quien lo hizo, use activa

Pasiva (interferencia comun)	Activa (mejor)
“The JWT is generated by the server"	"The server generates the JWT"
"The user data is stored in D1"	"We store user data in D1"
"Breaking changes were introduced"	"This PR introduces breaking changes”

4. Diferencias sutiles entre sinonimos

Palabra	Uso
Add	Nueva funcionalidad (no existia): “Add OAuth2 support”
Implement	Implementar un diseno conocido: “Implement the design from #123”
Create	Generar un nuevo objeto: “Create JWT service”
Build	Construir sistema: “Build the CI/CD pipeline”
Refactor	Mejorar codigo existente sin cambiar funcionalidad: “Refactor auth middleware”
Optimize	Mejorar rendimiento: “Optimize query performance”
Fix	Corregir bug: “Fix race condition in cache”

Lista de verificacion rapida para PR

Antes de enviar un PR, verifique:

La seccion What explica claramente el cambio
La seccion Why tiene razon de negocio o tecnica (no solo “quise hacerlo”)
La seccion How describe el diseno de alto nivel, el revisor no necesita leer codigo linea por linea
La seccion Testing indica la cobertura de pruebas
Sin exceso de voz pasiva
Articulos correctos (“the” vs “a”)
Tiempo verbal consistente (presente para funcionalidad del codigo, pasado para cambios)
Enlace a issue relacionado (si existe)

Lista de verificacion rapida para README

La primera oracion dice claramente que es el proyecto
Tiene demo o captura de pantalla
Los pasos de instalacion son claros y reproducibles
Los ejemplos de uso se pueden copiar directamente
Tiene guia de contribucion (si acepta contribuciones externas)
Tiene licencia
Lenguaje conciso (ni demasiado academico ni demasiado casual)