Plantilla de Linea de Tiempo de Deprecacion

Descripcion General

Deprecar una capacidad o API es facil de anunciar y dificil de terminar. Los usuarios se pierden el correo, las integraciones se rompen en el ultimo minuto y el equipo se queda atascado soportando un sistema que creia muerto. Una linea de tiempo de deprecacion es un contrato entre el equipo y sus consumidores: aqui esta lo que termina, cuando termina, que debes usar en su lugar y como te ayudaremos a migrar.

Cuando Usar

• For alternatives, see Monolith to Microservices — Migration Strategies.

Usa esta plantilla cuando:

• Un endpoint de API, capacidad o integracion esta siendo reemplazado por una version mas nueva
• Una dependencia de terceros esta llegando a fin de vida
• Un servicio esta siendo consolidado en otro sistema
• Una libreria cliente o version de SDK esta siendo retirada
• Una herramienta interna esta siendo reemplazada y otros equipos necesitan tiempo para adaptarse

Requisitos Previos

Antes de anunciar la deprecacion:

• El reemplazo esta disponible y documentado
• Existe documentacion de migracion y ha sido probada
• Hay capacidad de soporte disponible para responder preguntas de consumidores
• Legal o cumplimiento ha revisado cualquier obligacion contractual
• Se ha decidido si se ofrecera un periodo de gracia o un corte definitivo

Solucion

# Linea de Tiempo de Deprecacion: `<Funcion / API / Servicio>`

> Propietario de la deprecacion: ______ | Fecha: ______ | Apagado objetivo: ______
> Reemplazo: ______ | Canal de comunicacion: ______

## 1. Resumen de la Deprecacion

- **Que se esta deprecando:** ______
- **Por que se esta deprecando:** ______
- **Que lo reemplaza:** ______
- **Quien se ve afectado:** ______
- **Fecha final de apagado:** ______

## 2. Linea de Tiempo

| Hito | Fecha | Descripcion | Responsable | Estado |
|------|-------|-------------|-------------|--------|
| Anuncio | ______ | Notificacion publica de deprecacion | ______ | ______ |
| Documentacion | ______ | Guia de migracion publicada | ______ | ______ |
| Ejemplos de codigo | ______ | Migraciones de ejemplo en todos los lenguajes soportados | ______ | ______ |
| Advertencia suave | ______ | La API o UI comienza a mostrar avisos de deprecacion | ______ | ______ |
| Advertencia fuerte | ______ | Frecuencia o severidad de avisos aumentada | ______ | ______ |
| Congelamiento de capacidades | ______ | Sin nuevas capacidades en el sistema deprecado | ______ | ______ |
| Corte final | ______ | El sistema deprecado deja de responder | ______ | ______ |
| Post-apagado | ______ | Tickets de soporte y retrospectiva | ______ | ______ |

## 3. Plan de Comunicacion

| Audiencia | Canal | Mensaje | Fecha |
|-----------|-------|---------|-------|
| Equipos internos | ______ | ______ | ______ |
| Desarrolladores externos | ______ | ______ | ______ |
| Clientes enterprise | ______ | ______ | ______ |
| Equipo de soporte | ______ | ______ | ______ |
| Marketing / comunidad | ______ | ______ | ______ |

### Plantillas de mensaje

**Anuncio:**
> Estamos deprecando ______ el ______. Sera reemplazado por ______. La documentacion de migracion esta disponible en ______. Por favor migra antes de ______ para evitar interrupciones.

**Recordatorio a 30 dias:**
> Este es un recordatorio de que ______ sera apagado el ______. Si aun no has migrado, revisa ______ y contacta ______ para asistencia.

**Aviso final:**
> ______ sera apagado en 7 dias. Despues de ______, las peticiones a ______ retornaran ______. Para soporte urgente de migracion, contacta ______.

## 4. Ruta de Migracion

### Para consumidores usando ______

1. ______
2. ______
3. ______

### Cambios disruptivos

| Comportamiento anterior | Nuevo comportamiento | Accion requerida |
|-------------------------|----------------------|------------------|
| ______ | ______ | ______ |

## 5. Plan de Soporte

| Nivel de soporte | Disponibilidad | Contacto | Notas |
|------------------|----------------|----------|-------|
| Preguntas de migracion | ______ | ______ | ______ |
| Reportes de bugs en sistema deprecado | ______ | ______ | ______ |
| Solicitudes de funciones en sistema deprecado | ______ | ______ | ______ |

## 6. Rollback / Periodo de Gracia

- [ ] Periodo de gracia disponible: Si / No
- [ ] Duracion del periodo de gracia: ______
- [ ] Como solicitar periodo de gracia: ______
- [ ] Criterios de aprobacion: ______

## 7. Post-Apagado

- [ ] Monitorear trafico o errores inesperados por ______ dias
- [ ] Redirigir documentacion y links al reemplazo
- [ ] Archivar anuncio de deprecacion
- [ ] Actualizar catalogo de servicios para reflejar la remocion
- [ ] Realizar retrospectiva con consumidores afectados

Explicacion

La linea de tiempo es el nucleo de este documento. Cada hito da a los consumidores multiples oportunidades de notar y actuar. El plan de comunicacion asegura que el mensaje llegue a todas las audiencias a traves de sus canales preferidos. La ruta de migracion elimina la ambiguedad — los consumidores deben saber exactamente que cambiar. El plan de soporte establece expectativas: ayudaras, pero solo por un periodo definido. El periodo de gracia reconoce que las migraciones del mundo real se retrasan y te da una politica para manejar excepciones sin socavar la fecha limite.

Plantilla de Anuncio de Deprecacion

Asunto: [Accion Requerida] Deprecacion de [SISTEMA/API] — Efectivo [FECHA]

A todos los usuarios de [SISTEMA/API],

Anunciamos la deprecacion de [SISTEMA/API] efectiva [FECHA].
Este sistema sera apagado el [FECHA_APAGADO].

Por que lo deprecamos?
  [RAZON BREVE: ej., "El sistema ha sido reemplazado por [NUEVO_SISTEMA]
   que proporciona mejor rendimiento, confiabilidad y features."]

Que necesitas hacer?
  1. Revisa la guia de migracion: [LINK]
  2. Actualiza tu codigo para usar [NUEVO_SISTEMA] antes de [FECHA_LIMITE]
  3. Prueba tu integracion en staging antes de produccion
  4. Contacta a [EMAIL_EQUIPO] si necesitas soporte de migracion

Cronograma:
  - [FECHA]: Deprecacion anunciada (este email)
  - [FECHA+3meses]: Sin nuevas features ni bug fixes
  - [FECHA+6meses]: Sistema entra en modo solo lectura
  - [FECHA+9meses]: Sistema apagado

Soporte:
  - Guia de migracion: [LINK]
  - Horas de oficina: [DIA/HORA] para preguntas de migracion
  - Soporte directo: [EMAIL_EQUIPO]

Estamos comprometidos a hacer esta transicion lo mas suave posible.
Por favor contactanos si tienes alguna preocupacion.

[EQUIPO]

Dashboard de Seguimiento de Migracion

=== Tracker de Migracion de Deprecacion ===

Sistema: [NOMBRE_SISTEMA]
Fecha de Deprecacion: 2026-07-11
Fecha de Apagado: 2027-01-11

Consumidor       | Estado      | Ultimo Contacto | Nivel Riesgo | Notas
-----------------|-------------|-----------------|--------------|------------------
Equipo A (api)   | Migrado     | 2026-08-15      | Bajo         | Completado temprano
Equipo B (web)   | En Progreso | 2026-09-20      | Medio        | Necesita ayuda schema
Equipo C (movil) | No Iniciado | 2026-09-01      | Alto         | Sin respuesta aun
Equipo D (data)  | Migrado     | 2026-08-30      | Bajo         | Completado
Equipo E (infra) | En Progreso | 2026-09-25      | Medio        | Pruebas en staging

Resumen:
  Migrados:      2/5 (40%)
  En Progreso:   2/5 (40%)
  No Iniciados:  1/5 (20%)
  En Riesgo:     1/5 (20%)

Proximas Acciones:
  - Seguir con Equipo C (sin respuesta en 3 semanas)
  - Programar sesion de migracion con Equipo B
  - Verificar que pruebas de staging del Equipo E pasen

Variantes

Contexto	Ajustes	Notas
Deprecacion de API publica	Agregar entrada de changelog, post de blog para desarrolladores y cronograma de actualizacion de SDK	Las APIs publicas tienen mas consumidores y mayor visibilidad
Deprecacion de servicio interno	Agregar soporte de migracion del equipo propietario y seguimiento de Jira por consumidor	Los consumidores internos esperan soporte mas directo
Sunset de libreria cliente	Agregar matriz de compatibilidad de versiones y flags de deprecacion de npm/artefactos	Los gestores de paquetes tienen mecanismos de deprecacion integrados
Remocion de feature flag	Agregar analitica de uso del flag y plan de despliegue gradual	Saber quien aun tiene el flag habilitado
Fin de vida de dependencia de terceros	Agregar comunicacion con el proveedor, revision de contrato y evaluacion de alternativas	No controlas la linea de tiempo

Lo que funciona

1. Anuncia temprano, corta firmemente — da el maximo aviso, luego cumple la fecha
2. Haz la migracion mas facil que quedarse — ejemplos de codigo, herramientas CLI y documentacion clara reducen la carga de soporte
3. Monitorea la adopcion — rastrea cuantos consumidores han migrado; apunta a los rezagados directamente
4. No agregues funciones a un sistema deprecado — senala que la deprecacion no es seria
5. Documenta la decision — escribe un ADR o breve explicando por que el sistema se esta deprecando

Errores Comunes

1. Anunciar sin reemplazo — los consumidores no pueden migrar a la nada
2. Un correo y listo — la gente pierde correos; comunica repetidamente a traves de multiples canales
3. Sin corte definitivo — las deprecaciones suaves nunca terminan; establece una fecha real
4. Ignorar contratos enterprise — algunos clientes tienen SLAs que requieren aviso anticipado
5. Olvidar la documentacion — viejos posts de blog, respuestas de Stack Overflow y READMEs viven para siempre

Referencia Rápida

• Comando principal: ejecuta la solución base del artículo y verifica el resultado esperado.
• Validación: confirma que los tests pasan y que las métricas clave no se degradaron.
• Rollback: si algo falla, revierte el cambio y consulta la sección de Troubleshooting.

Lectura Adicional

• Documentación oficial: consulta la referencia actualizada del framework o herramienta utilizada.
• Guías relacionadas: explora las guías de deprecation y legacy para profundizar.
• Patrones complementarios: revisa los patrones de diseño aplicables a tu stack tecnológico.
• Postmortems públicos: estudia incidentes reales de equipos que enfrentaron problemas similares en producción.

Notas de Producción

• Despliega gradualmente usando canary o blue-green para detectar regresiones temprano.
• Configura alertas para errores, latencia p99 y tasa de fallos antes de habilitar en producción.
• Documenta el rollback en el runbook; prueba el procedimiento en staging al menos una vez por trimestre.
• Revisa logs estructurados con correlation IDs para trazar requests end-to-end en incidentes.

Puntos Clave

• Aplica plantilla de linea de tiempo de deprecacion cuando necesites una solución práctica para tu caso de uso.
• Monitorea el rendimiento después de implementar; mide latencia, errores y uso de recursos antes y después.
• Revisa la sección de Troubleshooting ante errores comunes; la mayoría tienen causa raíz documentada con solución.
• Mantén dependencias actualizadas y ejecuta tests en CI para prevenir regresiones en producción.

Troubleshooting

• Pipeline fails silently: enable verbose logging and store pipeline artifacts between stages so you can inspect the exact state that failed.
• Container crashes on startup: check that environment variables, secrets, and config files are mounted correctly. Read the first 50 lines of logs before scaling replicas.
• Deployment rolls back repeatedly: verify health checks, resource limits, and startup probes. A failing readiness probe is a common cause of rolling restarts.
• Slow CI builds: cache dependencies and docker layers. Split large test suites into parallel jobs to reduce wall-clock time.
• Drift between environments: use infrastructure-as-code and immutable artifacts.

Errores Comunes en Producción

• Dejar campos requeridos vacíos o usar respuestas vagas de una palabra.
• Llenar el documento una vez y nunca actualizarlo cuando cambia el alcance o las decisiones.
• Guardar el documento donde el equipo no lo busque durante incidentes o revisiones.
• No asignar un responsable, fecha límite o cadencia de revisión.
• Copiar texto base sin eliminar secciones que no aplican.
• Saltar el control de versiones, lo que impide rollback y responsabilidad.
• No vincular el documento con decisiones relacionadas o acciones de seguimiento.
• Evitar revisiones trimestrales que retirarían secciones obsoletas o sin uso.