Guías de migración que la gente puede seguir

Un aviso de obsolescencia dice que algo está cambiando. No dice qué hacer al respecto. Eso es un documento aparte, y responde a cuatro preguntas en orden:

1. Qué cambió. El campo o el comportamiento concreto, nombrado con exactitud. No «se mejoró el formato de la respuesta».
2. Cómo era antes y cómo es después. Un par real de cuerpos de respuesta, no una descripción de uno.
3. Qué acción hace falta, si hace falta alguna. A veces la respuesta es «ninguna, esto es un añadido», y decirlo le ahorra a un consumidor un trabajo innecesario.
4. Cuál es el calendario. Las mismas dos fechas que llevan las cabeceras, en lenguaje llano.

## Respuesta de licencia: v1 -> v2

Qué cambió
  Se añadió `status`. No se quitó ni se renombró nada.

Antes (v1)
  { "key": "lic_123", "name": "...", "domains": [...] }

Después (v2)
  { "key": "lic_123", "name": "...", "domains": [...],
    "status": "active" }

Acción necesaria
  Ninguna, salvo que quieras leer `status`.

Calendario
  v1 obsoleta el 1 de marzo de 2027.
  v1 deja de funcionar el 1 de septiembre de 2027.

Escribe la guía antes de escribir el aviso de obsolescencia. Si no puedes rellenar las cuatro secciones con claridad, el cambio no está listo para entregarse.

Retirar una versión

Retirar una versión son dos decisiones que parecen una: decidir que es seguro, y decidir hacerlo. No dejes que la segunda ocurra antes de que la primera sea verdad.

La seguridad sale de los datos, no del calendario. Mira el log de peticiones antes de que llegue la fecha de retirada. Si el tráfico de v1 no ha bajado a cero, o a una lista corta de consumidores con los que ya hablaste, mueve la fecha. No la ignores.

Una vez que el tráfico ha desaparecido, retirar es borrar, no dejar un indicador puesto «por si acaso». Elimina el caso V1 del enum, elimina la condición del Resource para que status esté siempre presente, y borra sus fechas de la configuración.

Resumen del capítulo 16

Antes de poner versión a nada:

• Ten claro si el cambio es un añadido o es incompatible antes de escribirlo.
• Resuelve la versión una vez, en el borde, en un middleware.
• Varía el Resource, nunca el código que obtiene los datos.

Antes de declarar algo obsoleto:

• Ponle a la versión una fecha real de obsolescencia y una fecha real de retirada.
• Avisa a los consumidores realmente afectados, más de una vez. Las cabeceras solas no son un aviso.
• Escribe primero la guía de migración.

Antes de retirar:

• Confirma en el log de peticiones que el tráfico ha desaparecido o está identificado.
• Borra por completo el camino viejo.