Un aviso de deprecación le dice a quien consume que algo está cambiando. No le dice qué hacer al respecto. Eso es un documento aparte, y tiene que responder a cuatro preguntas en orden:
- Qué cambió. El campo, comportamiento o tipo concreto, nombrado exactamente, no «se mejoró el formato de la respuesta».
- Cómo era antes y cómo es ahora. Un par real de carga antes/después, no una descripción de uno.
- Qué acción hace falta, si es que hace falta alguna. A veces la respuesta es «ninguna, esto es aditivo», y decirlo explícitamente ahorra trabajo innecesario.
- Cuál es el calendario. Las mismas fechas que llevan las cabeceras, repetidas en lenguaje llano.
// docs/migrations/2026-license-v2.md
## License response: v1 → v2
### What changed
`status` was added to the license response. Nothing was removed or renamed.
### Before (v1)
{ "key": "lic_123", "name": "...", "domains": [...], "created_at": "..." }
### After (v2)
{ "key": "lic_123", "name": "...", "domains": [...], "created_at": "...", "status": "active" }
### Action required
None if you don't read `status`. Read it if you want to stop polling for
expiration separately.
### Timeline
v1 deprecated 2026-09-01. v1 stops responding 2027-01-15.
Escribe la guía antes que el aviso de deprecación, no después. Si no puedes rellenar las cuatro secciones con claridad, probablemente el cambio no esté listo para publicarse.
Retirar una version
Retirar una versión son dos decisiones separadas disfrazadas de una: decidir que es seguro y decidir hacerlo. No dejes que la segunda ocurra antes de que la primera sea cierta de verdad.
La seguridad viene de los datos, no sólo del calendario. LogApiRequestsMiddleware ya registra cada petición; en cuanto el middleware de versión fija api_version en la petición, ese valor viaja gratis en la misma línea de registro. Consúltalo antes de tocar la fecha de retirada: si el tráfico de v1 no ha caído a cero (o a una lista pequeña, conocida y ya avisada) para la fecha que elegiste, mueve la fecha, no la ignores.
Una vez el tráfico ha desaparecido de verdad, retirar es borrar, no dejar una bandera «por si acaso». Elimina el caso V1 del enum, promociona el cuerpo del resource nuevo al original, borra la rama del controlador, borra las fechas del caso que ya no existe. Una versión que sigues sirviendo después de su fecha de retirada no es prudencia: es una promesa que rompiste en la otra dirección. Dijiste que dejaría de funcionar y no lo hizo, lo que significa que la siguiente fecha de retirada que publiques valdrá menos que la anterior.
Antes de versionar nada:
- [X] Sabe si el cambio es aditivo o rompedor antes de escribirlo
- [X] Resuelve la versión una vez, en el borde, en un middleware, no esparcida por los controladores
Antes de deprecar:
- [X] Pon fechas reales de deprecación y retirada, no una promesa vaga
- [X] Envía al menos tres avisos a los consumidores registrados, no sólo cabeceras de respuesta
Antes de retirar:
- [X] Confirma con registros reales que el tráfico de esa versión se ha ido o está plenamente identificado
- [X] Borra el camino de código antiguo por completo una vez retirado
Una versión que nunca retiras no es estabilidad. Es una deuda por la que sigues pagando intereses.