Plantilla de línea de tiempo de deprecación
Plantilla para planificar y comunicar la retirada de funcionalidades, APIs o servicios heredados, con hitos claros y notificaciones a los interesados.
Descripción general
Anunciar la deprecación de una funcionalidad o API es fácil; terminarla es lo difícil. Los usuarios no leen el correo, las integraciones se rompen en el último momento y el equipo sigue manteniendo un sistema que todos daban por muerto meses atrás. Una línea de tiempo de deprecación funciona como un contrato entre tu equipo y sus consumidores: qué termina, cuándo termina, qué usar en su lugar y cómo vais a ayudar a la gente a llegar hasta ahí.
Esta plantilla cubre todo el arco, desde el primer anuncio hasta la limpieza posterior al apagado. Rellena los huecos una vez y mantén el documento al día a medida que cambien las fechas.
Cuándo usarla
Usa esta plantilla cuando:
- Un endpoint de API, funcionalidad o integración se reemplaza por una versión más reciente
- Una dependencia de terceros llega a su fin de vida
- Un servicio se consolida dentro de otro sistema
- Se retira una versión de una librería cliente o SDK
- Se reemplaza una herramienta interna y otros equipos necesitan tiempo para adaptarse
Para el mensaje de anuncio en sí, combínala con la Plantilla de aviso de deprecación de API. Para campos de un esquema GraphQL, usa la Plantilla de política de deprecación de GraphQL. Si la migración es arquitectónica y no un simple reemplazo, consulta De monolito a microservicios — Estrategias de migración.
Requisitos previos
Antes de anunciar la deprecación:
- El reemplazo está disponible y documentado
- La documentación de migración existe y se ha probado
- Hay capacidad de soporte para responder a las preguntas de los consumidores
- Legal o cumplimiento ha revisado las obligaciones contractuales
- Se ha decidido si se ofrecerá un período de gracia o un corte definitivo
Solución
# Línea de tiempo de deprecación: `<Funcionalidad / API / Servicio>`
> Responsable de la deprecación: ______ | Fecha: ______ | Apagado previsto: ______
> Reemplazo: ______ | Canal de comunicación: ______
## 1. Resumen de la deprecación
- **Qué se depreca:** ______
- **Por qué se depreca:** ______
- **Qué lo reemplaza:** ______
- **A quién afecta:** ______
- **Fecha final de apagado:** ______
## 2. Línea de tiempo
| Hito | Fecha | Descripción | Responsable | Estado |
|------|-------|-------------|-------------|--------|
| Anuncio | ______ | Notificación pública de la deprecación | ______ | ______ |
| Documentación | ______ | Guía de migración publicada | ______ | ______ |
| Ejemplos de código | ______ | Migraciones de ejemplo en todos los lenguajes soportados | ______ | ______ |
| Aviso suave | ______ | La API o UI empieza a mostrar avisos de deprecación | ______ | ______ |
| Aviso fuerte | ______ | Mayor frecuencia o severidad de los avisos | ______ | ______ |
| Congelación de funcionalidades | ______ | Sin nuevas funcionalidades en el sistema deprecado | ______ | ______ |
| Corte final | ______ | El sistema deprecado deja de responder | ______ | ______ |
| Post-apagado | ______ | Tickets de soporte y retrospectiva | ______ | ______ |
## 3. Plan de comunicación
| Audiencia | Canal | Mensaje | Fecha |
|-----------|-------|---------|-------|
| Equipos internos | ______ | ______ | ______ |
| Desarrolladores externos | ______ | ______ | ______ |
| Clientes empresariales | ______ | ______ | ______ |
| Equipo de soporte | ______ | ______ | ______ |
| Marketing / comunidad | ______ | ______ | ______ |
### Plantillas de mensajes
**Anuncio:**
> Deprecamos ______ a partir del ______. Será reemplazado por ______. La documentación de migración está disponible en ______. Migra antes del ______ para evitar interrupciones.
**Recordatorio a 30 días:**
> Este es un recordatorio de que ______ se apagará el ______. Si aún no has migrado, revisa ______ y contacta con ______ para obtener ayuda.
**Aviso final:**
> ______ se apagará en 7 días. Después del ______, las peticiones a ______ devolverán ______. Para soporte urgente de migración, contacta con ______.
## 4. Ruta de migración
### Para consumidores que usan ______
1. ______
2. ______
3. ______
### Cambios incompatibles
| Comportamiento anterior | Comportamiento nuevo | Acción requerida |
|------------------------|---------------------|------------------|
| ______ | ______ | ______ |
## 5. Plan de soporte
| Nivel de soporte | Disponibilidad | Contacto | Notas |
|------------------|----------------|----------|-------|
| Preguntas de migración | ______ | ______ | ______ |
| Reportes de bugs en el sistema deprecado | ______ | ______ | ______ |
| Peticiones de funcionalidades en el sistema deprecado | ______ | ______ | ______ |
## 6. Rollback / Período de gracia
- [ ] Período de gracia disponible: Sí / No
- [ ] Duración del período de gracia: ______
- [ ] Cómo solicitar el período de gracia: ______
- [ ] Criterios de aprobación: ______
## 7. Post-apagado
- [ ] Monitorizar tráfico o errores inesperados durante ______ días
- [ ] Redirigir la documentación y los enlaces al reemplazo
- [ ] Archivar el anuncio de deprecación
- [ ] Actualizar el catálogo de servicios para reflejar la retirada
- [ ] Realizar una retrospectiva con los consumidores afectadosExplicación
La línea de tiempo es el núcleo de este documento. Cada hito da a los consumidores otra oportunidad de enterarse y actuar, y cada fecha es un compromiso que no puedes retirar en silencio. El plan de comunicación pone el mensaje delante de cada audiencia en los canales que realmente lee. La ruta de migración elimina la ambigüedad: los consumidores deben saber exactamente qué cambiar. El plan de soporte fija las expectativas: ayudarás, pero solo durante un período definido. El período de gracia reconoce que las migraciones reales se retrasan y te da una política para las excepciones que no debilita la fecha límite.
Ejemplo práctico
Así queda la línea de tiempo rellenada para un escenario real: payments-api v1 se retira en favor de v2, con 34 servicios consumidores conocidos, cuatro de ellos de clientes empresariales con cláusulas contractuales de preaviso.
# Línea de tiempo de deprecación: payments-api v1
> Responsable: equipo payments-platform | Fecha: 2027-01-15 | Apagado previsto: 2027-10-15
> Reemplazo: payments-api v2 | Canal: #payments-announce + página de estado
## 2. Línea de tiempo
| Hito | Fecha | Descripción | Responsable | Estado |
|------|-------|-------------|-------------|--------|
| Anuncio | 2027-01-15 | Post en el blog, changelog, correo directo a los 10 mayores consumidores | PM | Hecho |
| Documentación | 2027-02-01 | Guía de migración v1→v2 publicada | DevRel | Hecho |
| Ejemplos de código | 2027-02-15 | Ejemplos de migración en JS, Python, Java | Equipo payments | Hecho |
| Aviso suave | 2027-04-01 | Cabeceras `Deprecation` y `Sunset` en todas las respuestas de v1 | Backend | Hecho |
| Aviso fuerte | 2027-07-01 | Correos semanales a los responsables de servicios que siguen llamando a v1 | PM | Programado |
| Congelación de funcionalidades | 2027-07-15 | Sin nuevas funcionalidades en v1; solo correcciones críticas | Backend | Programado |
| Corte final | 2027-10-15 | v1 devuelve HTTP 410 con enlace a la migración | Backend | Programado |
| Post-apagado | 2027-11-15 | Fin de la monitorización de tráfico; retrospectiva | PM | Programado |Aquí importan dos detalles. Primero, las fechas: nueve meses en total, con unos tres meses entre el aviso suave y el corte final. Segundo, los avisos HTTP son legibles por máquina. Las cabeceras de respuesta Deprecation y Sunset (RFC 9745 y RFC 8594) permiten que las herramientas del cliente detecten la retirada sin que una persona lea el post.
Dimensionar la línea de tiempo
Cuánto preaviso es suficiente depende de quién consume lo que retiras:
| Alcance | Preaviso sugerido | Por qué |
|---|---|---|
| Herramienta interna, <10 consumidores conocidos | 1–2 meses | Hay canales directos; puedes perseguir a personas concretas |
| Servicio interno de toda la organización | 3–4 meses | Aparecerán tarde consumidores que no conocías |
| API de partners o privada | 6 meses | Otras empresas planifican sus sprints en torno a tus fechas |
| API pública o SDK | 9–12 meses | Consumidores desconocidos; las revisiones de stores y vendors añaden retraso |
Deja margen en cada hito, no solo en la fecha final. El fallo más común no es el corte en sí, sino una guía de migración que sale dos meses después del anuncio y quema el período de preaviso que los consumidores realmente necesitaban.
Cuándo NO usar esta plantilla
- Apagados de emergencia por seguridad. Si una vulnerabilidad te obliga a desconectar en días, estás gestionando un incidente, no una deprecación. Usa un plan de comunicación de incidentes y sé honesto: la fecha está dictada, no negociada.
- Refactors internos de un solo equipo. Si un equipo es dueño de todos los llamadores, basta un épico en Jira y un mensaje en Slack. Esta plantilla compensa cuando los consumidores superan a las personas a las que puedes escribir.
- Limpieza de feature flags. Retirar un flag que controla comportamiento de UI rara vez necesita un arco de 9 meses. Revisa las métricas de uso del flag, avisa a los pocos equipos que aún dependen de él y bórralo.
Plantilla de anuncio de deprecación
El documento de línea de tiempo planifica la retirada internamente; el anuncio es lo que los consumidores ven de verdad. Mantén ambos sincronizados: cada fecha del mensaje público debe coincidir con la línea de tiempo.
Asunto: [Acción requerida] Deprecación de [SISTEMA/API] — En vigor el [FECHA]
A todos los usuarios de [SISTEMA/API]:
Anunciamos la deprecación de [SISTEMA/API] con efecto el [FECHA].
Este sistema se apagará el [FECHA_DE_APAGADO].
¿Por qué lo deprecamos?
[RAZÓN BREVE: p. ej., "El sistema ha sido reemplazado por [NUEVO_SISTEMA],
que ofrece mejor rendimiento, fiabilidad y funcionalidades."]
¿Qué necesitas hacer?
1. Revisa la guía de migración: [ENLACE]
2. Actualiza tu código para usar [NUEVO_SISTEMA] antes del [FECHA_LÍMITE_MIGRACIÓN]
3. Prueba tu integración en staging antes de producción
4. Contacta con [EMAIL_DEL_EQUIPO] si necesitas ayuda con la migración
Línea de tiempo:
- [FECHA]: Deprecación anunciada (este correo)
- [FECHA+3m]: Sin nuevas funcionalidades ni correcciones de bugs
- [FECHA+6m]: El sistema pasa a modo solo-lectura
- [FECHA+9m]: El sistema se apaga
Soporte:
- Guía de migración: [ENLACE]
- Horario de oficina: [DÍA/HORA] para preguntas de migración
- Soporte directo: [EMAIL_DEL_EQUIPO]
Estamos comprometidos a que esta transición sea lo más suave posible.
Escríbenos si tienes cualquier duda.
[NOMBRE_DEL_EQUIPO]Para profundizar en el aviso en sí (asuntos, estrategia de canales, cadencia de reenvíos), consulta la Plantilla de aviso de deprecación de API.
Panel de seguimiento de la migración
Los anuncios se olvidan; el seguimiento mantiene la fecha real. Un panel compartido sencillo responde a la única pregunta que importa: ¿quién queda?
=== Panel de seguimiento de migración ===
Sistema: payments-api v1
Fecha de deprecación: 2027-01-15
Fecha de apagado: 2027-10-15
Consumidor | Estado | Último contacto | Riesgo | Notas
----------------|--------------|-----------------|--------|------------------
Equipo A (api) | Migrado | 2027-03-15 | Bajo | Completó pronto
Equipo B (web) | En progreso | 2027-04-20 | Medio | Necesita ayuda con el esquema
Equipo C (móvil)| Sin empezar | 2027-04-01 | Alto | Sin respuesta aún
Equipo D (data) | Migrado | 2027-03-30 | Bajo | Completado
Equipo E (infra)| En progreso | 2027-04-25 | Medio | Probando en staging
Resumen:
Migrados: 2/5 (40%)
En progreso: 2/5 (40%)
Sin empezar: 1/5 (20%)
En riesgo: 1/5 (20%)
Próximas acciones:
- Retomar contacto con el Equipo C (sin respuesta en 3 semanas)
- Programar sesión de migración con el Equipo B
- Verificar que las pruebas de staging del Equipo E pasanRevisa tres señales cada semana: número de migrados, tráfico restante en el sistema viejo y tickets de soporte. Cuando el número de migrados se estanca dos semanas seguidas, cambia de los recordatorios generales a contacto directo con los equipos que siguen en la lista.
Variantes
| Contexto | Ajustes | Notas |
|---|---|---|
| Deprecación de API pública | Añade entrada en el changelog, post en el blog de desarrolladores y calendario de actualización del SDK | Las APIs públicas tienen más consumidores y mayor visibilidad |
| Deprecación de servicio interno | Añade soporte de migración del equipo propietario y seguimiento por consumidor en Jira | Los consumidores internos esperan soporte más directo |
| Retirada de librería cliente | Añade matriz de compatibilidad de versiones y flags de deprecación en npm/artefactos | Los gestores de paquetes tienen mecanismos de deprecación integrados |
| Eliminación de feature flag | Añade analítica de uso del flag y plan de retirada por fases | Debes saber quién sigue teniendo el flag activo |
| Fin de vida de dependencia externa | Añade comunicación con el vendor, revisión de contrato y evaluación de alternativas | Tú no controlas la línea de tiempo |
Lo que funciona
- Anuncia pronto, corta con firmeza: da el máximo preaviso y luego respeta la fecha
- Haz que migrar sea más fácil que quedarse: ejemplos de código, herramientas CLI y documentación clara reducen la carga de soporte
- Monitoriza la adopción: sigue cuántos consumidores han migrado y persigue directamente a los rezagados
- No añadas funcionalidades al sistema deprecado. Eso indica que la deprecación no va en serio
- Documenta la decisión: escribe un ADR o un brief que explique por qué se depreca el sistema
- Revisa la línea de tiempo cada trimestre. Las fechas se mueven, y una línea de tiempo desactualizada enseña a los consumidores a ignorar todas tus fechas
Errores comunes
- Anunciar sin un reemplazo: los consumidores no pueden migrar a la nada
- Un correo y listo. La gente no lee los correos, así que comunica de forma repetida y por varios canales
- Sin corte definitivo. Las deprecaciones suaves nunca terminan, así que fija una fecha real
- Ignorar los contratos empresariales. Algunos clientes tienen SLAs que exigen preaviso
- Olvidar la documentación antigua. Los posts viejos, las respuestas de Stack Overflow y los READMEs viven para siempre
- Sin responsable ni cadencia de revisión. Una línea de tiempo que nadie actualiza se convierte en ficción en un trimestre
- Dejar secciones de la plantilla en blanco. Las secciones vacías indican que el plan no es real; borra lo que no aplique
Véase también
- RFC 9745 — The Deprecation HTTP Response Header: señal de deprecación legible por máquina para APIs
- RFC 8594 — The Sunset HTTP Header Field: anuncia la fecha de apagado prevista en las respuestas
- El enfoque de Stripe sobre versionado de APIs: cómo una API mayor evoluciona sin romper a sus consumidores
- Microsoft REST API Guidelines — deprecation: convenciones empresariales para cambios incompatibles
- Plantilla de aviso de deprecación de API: el artefacto de anuncio que complementa esta línea de tiempo
- Plantilla de política de deprecación de GraphQL: deprecación a nivel de campo para esquemas
- Repositorio de recursos complementarios: ejemplo rellenado, CSV de seguimiento y snippets de cabeceras de aviso
Preguntas frecuentes
¿Cuánto preaviso deberíamos dar?
Para APIs públicas, lo habitual son 6–12 meses. Para servicios internos, 3 meses pueden bastar si tienes canales directos. Cuantos más consumidores tengas, más preaviso necesitas. Los clientes empresariales pueden exigir períodos de preaviso definidos por contrato.
¿Qué pasa si un cliente crítico no puede migrar a tiempo?
Ten una política de período de gracia documentada antes de anunciar. No hagas excepciones improvisadas; eso debilita la línea de tiempo para todos los demás. Si se aprueba un período de gracia, fija una segunda fecha firme y comunícala con transparencia.
¿Deberíamos mantener la API vieja devolviendo una redirección?
Durante un período corto tras el apagado (días, no meses), un error claro con enlace a la documentación de migración ayuda a los rezagados. Las redirecciones permanentes ocultan el problema y retrasan la migración. Al final, el endpoint debería devolver un error definitivo como HTTP 410.
¿Cómo gestionamos la deprecación para consumidores internos frente a externos?
Los consumidores internos reciben comunicación directa (Slack, reuniones de equipo), seguimiento de migración por equipo y escalado a los engineering managers cuando un equipo no responde. Los externos reciben canales públicos (post, página de estado, correo), guías de migración detalladas con ejemplos de código y períodos de preaviso contractuales. Las deprecaciones internas pueden cerrarse en ~3 meses; las externas necesitan 6–12.
¿Qué métricas deberíamos seguir durante una deprecación?
Sigue consumidores migrados frente al total, tráfico que aún llega al sistema deprecado, tasa de errores, tickets de soporte relacionados con la migración y días hasta el apagado. Alarma cuando la migración se estanque: dos semanas sin nuevas migraciones significa que los recordatorios generales dejaron de funcionar y toca contacto directo.
¿Cómo gestionamos una deprecación que afecta a clientes de pago?
Revisa los contratos para conocer los requisitos de preaviso antes de anunciar nada. Avisa a los clientes clave a través de los account managers antes del anuncio público. Ofrece plazos extendidos si los contratos lo exigen y da soporte de migración directo a las cuentas top. Nunca permitas que un cliente de pago se entere de un apagado por un post público.
¿Qué pasa si el sistema de reemplazo no está listo cuando necesitamos deprecar?
Retrasa el anuncio hasta que lo esté. Deprecar hacia un reemplazo inexistente obliga a los consumidores a construir sus propias soluciones y fragmenta el ecosistema. Si problemas de seguridad obligan a un apagado anticipado, comunica el riesgo con honestidad y ofrece un puente: una capa de compatibilidad o un reemplazo mínimo viable.
¿Cómo comunicamos el apagado final?
Envía un recordatorio final una semana antes, actualiza la página de estado el día del apagado y monitoriza el tráfico residual para pillar a quien se perdió todos los avisos. Conserva los logs de error 30 días para identificar consumidores despistados. Cuando el tráfico se mantenga en cero, desmantela la infraestructura y haz la retrospectiva.
Recursos Relacionados
Plantilla de Aviso de Deprecación de API
Plantilla para comunicar deprecaciones de API, cambios breaking y plazos de retiro a los consumidores.
DocPlantilla de Política de Deprecación de GraphQL
Plantilla de política para deprecar campos, tipos y valores enum de GraphQL sin romper clientes, con cronogramas, seguimiento de uso y ejemplos de migración.
DocPlantilla de Checklist de Desmantelamiento
Una checklist para retirar servicios antiguos de forma segura: eliminar dependencias y limpiar infraestructura sin romper a los consumidores.
DocPlantilla del Ciclo de Vida de APIs
Una plantilla de checklist lista para copiar para gestionar la deprecación de APIs, las transiciones de versionado y los cierres seguros.
DocPlantilla de Changelog de API
Plantilla para documentar cambios de API incluyendo cambios breaking, nuevas capacidades, deprecaciones y correcciones.
GuideDe Monolito a Microservicios — Estrategias de Migración
Guía práctica para descomponer monolitos: strangler fig, branch by abstraction y extracción incremental que reducen riesgo y preservan la continuidad del negocio.