Deprecation
Comunicar una transición de lifecycle
En el Atlas, Deprecation describe el estado y proceso mediante el cual un proveedor comunica que una capacidad deja de ser preferida para nuevos usos y que sus consumidores deben preparar una alternativa o su eventual retirada. Puede aplicarse a una interface, versión, recurso o comportamiento. Es una definición operativa para razonar sobre evolución, no una política universal de soporte.
Deprecar conserva una diferencia esencial: dejar de recomendar algo no significa quitarlo de operación. Una capacidad puede seguir atendiendo requests, recibiendo mantenimiento y correcciones de seguridad mientras sus consumidores se adaptan. El compromiso concreto depende de la política y de los contratos vigentes.
sunsetting aborda la retirada controlada. Ambos conceptos pueden conectarse, pero no son etapas obligatorias de todo sistema: una capacidad puede permanecer deprecated indefinidamente o retirarse por una emergencia sin una transición prolongada. Tampoco toda deprecation promete una futura eliminación.
Estado, soporte y comportamiento son preguntas distintas
| Término | Qué permite afirmar |
|---|---|
| Deprecated | El proveedor comunica que se abandone progresivamente esa dependencia según una política. |
| Removed | El elemento ya no está presente o disponible en el alcance y versión indicados. |
| Unsupported | El soporte ha terminado bajo las condiciones declaradas por quien lo ofrece. |
| Broken / inseguro | Existe un problema de funcionamiento o seguridad que necesita evidencia propia. |
Una API deprecated puede seguir siendo correcta, soportada y segura. Otra API puede perder soporte sin haber recibido avisos útiles. No se deducen esas propiedades de una etiqueta; preguntar qué comportamiento y asistencia continúan disponibles evita decisiones falsas de urgencia.
Los motivos pueden incluir simplificar un contrato, cambiar un modelo de seguridad, reducir costo de operación, abandonar una dependencia o preferir una alternativa. La etiqueta tampoco demuestra que el diseño anterior fuera malo u obsoleto para su contexto original. Explicar el motivo ayuda a comprender qué dependencia conviene evitar.
Alcance: qué se está deprecando
El objeto puede ser un endpoint, una versión completa de API, un campo, una variante de evento, un método de biblioteca, una configuración, un protocolo, runtime, feature, integración o capacidad de producto. No requiere HTTP ni una arquitectura de servicios.
Precisar el alcance protege a consumidores que necesitan distinguir «este campo deja de recomendarse» de «todo el servicio termina». También importa dónde aplica: una versión nueva puede marcar un método como deprecated mientras versiones anteriores siguen sujetas a compromisos distintos. Cambiar una implementación privada puede no afectar ningún contrato consumido.
interfaces hace visible la superficie de dependencia. Una interface interna también puede tener consumidores desconocidos; «es nuestra» no demuestra que pueda alterarse sin coordinación. systems-thinking amplía la revisión hacia operaciones, socios y procesos fuera del equipo proveedor.
Comunicación que permita actuar
Un aviso útil permite responder qué elemento cambia, por qué, desde cuándo, qué alternativa existe, dónde encontrar guía y qué consecuencias tendría no migrar. Son preguntas de razonamiento, no campos obligatorios de metadata ni un template universal.
Documentación, release notes, advertencias de compilador, metadata de contratos, mensajes en runtime, dashboards y comunicación directa son superficies posibles. Elegirlas según cómo trabajan los consumidores. Un script mantenido esporádicamente puede no consultar el portal donde se publicó el aviso; una advertencia solo visible al compilar puede no alcanzar un binario ya instalado.
La información necesita ser descubrible y accionable. «Deprecated» sin identificar el comportamiento afectado deja trabajo de investigación a cada usuario. Repetir indefinidamente un warning sin guía o deprecar grandes superficies juntas puede generar fatiga y competir con otras prioridades. La visibilidad no demuestra comprensión ni adopción.
Alternativas y fechas con significado explícito
Una alternativa puede ser v2, otra capacidad o la combinación de varias operaciones; no tiene que conservar estructura uno a uno. También puede no existir reemplazo porque se abandona el comportamiento o el producto. La guía necesita entonces explicar cómo dejar de depender de él, sin prometer una equivalencia inexistente.
Conviene separar fecha del anuncio, fecha efectiva de deprecation y eventual fecha de retirada cuando la política las utilice. Publicar hoy que un cambio entrará en vigor después no vuelve equivalentes esos momentos. Tampoco exige que todo caso tenga tres fechas.
Puede no conocerse todavía un sunset. Esa ausencia puede reducir la urgencia de migrar y prolongar costos de compatibilidad, pero no invalida la deprecation. Una fecha por sí sola tampoco establece una transición viable: faltan capacidad de los consumidores, cambios necesarios, asistencia y evidencia de preparación.
HTTP como ejemplo concreto
RFC 9745 define el campo de respuesta Deprecation para comunicar una fecha de deprecation de un recurso HTTP. El documento distingue esa información de modificar su comportamiento y ofrece la relación de enlace deprecation para descubrir documentación.
Su sección 4 permite añadir Sunset cuando se quiere comunicar una indisponibilidad esperada; esa fecha no debe preceder a la de deprecation. Son informaciones diferentes. La señal no garantiza comportamiento futuro permanente. Estos mecanismos pertenecen a HTTP: no son requisitos de todos los lifecycle del Atlas ni obligan a que una biblioteca o evento use headers.
Políticas concretas, sin mezclarlas
Semantic Versioning 2.0.0 vincula deprecation de una API pública con documentación y una release minor; su guía pide al menos una minor con la deprecation antes de eliminar funcionalidad en una major. Ese contexto de paquetes y releases que adoptan SemVer no establece que toda API distribuida deba retirarse mediante una major.
La política de Kubernetes diferencia APIs y otras superficies, sus niveles de estabilidad y condiciones de retirada. Por ejemplo, permite quitar versiones alpha de API sin aviso previo, mientras protege las GA dentro de una major. También documenta avisos y evidencia de uso de endpoints deprecated. Es un ejemplo de previsibilidad explícita, no una ventana que se copie a cualquier producto.
Una política situada puede definir alcance, comunicación, soporte, excepciones y condiciones de retirada. Relación con consumidores, distribución del software, contratos y riesgo cambian las opciones. Combinar ventanas de Kubernetes, SemVer y semántica HTTP como si fueran un estándar único inventaría obligaciones que esas fuentes no establecen.
Consumidores conocidos y uso que no se observa
El inventario inicial puede omitir scripts, BI, automatización, partners, jobs mensuales y clientes antiguos. legacy-systems recuerda que el conocimiento real está repartido entre software y personas. Entrevistas, análisis de dependencias y confirmación de responsables complementan logs y catálogos.
Counts de requests, identidades y versiones, uso de eventos, descargas de paquetes y trazas aportan señales distintas. Descargas no equivalen a ejecución; una dirección de proxy puede ocultar varios consumidores. Sampling, cachés, clientes offline, identidades ausentes y períodos de observación cortos limitan lo que puede inferirse.
Cero tráfico observado no prueba cero consumidores. Una prueba anual de recuperación o un cierre financiero puede quedar fuera de la ventana. En APIs públicas quizá nunca exista inventario completo; habrá que combinar política publicada, canales de aviso y evidencia, reconociendo incertidumbre residual en vez de prometer riesgo cero.
Coexistencia y migración efectiva
Una ventana de compatibilidad puede mantener contratos antiguos y nuevos utilizables mientras migran consumidores. parallel-change desarrolla un mecanismo para esa convivencia; Deprecation comunica su dirección de lifecycle. Versionar permite identificar contratos, pero no realiza adopción ni elimina soporte, pruebas y operación de versiones coexistentes.
migration-strategy organiza estados, secuencia, responsables y salida. El aviso no reemplaza decidir qué hacer con consumidores que no pueden migrar, qué obligaciones deben preservarse y cuándo revisar la política. La alternativa puede necesitar adaptación de negocio y no solo cambiar una URL.
fitness-functions puede apoyar criterios con uso de v1 descendente, confirmación de clientes requeridos en v2, cese de un evento o ausencia de una dependencia prohibida. Cada evaluación tiene alcance y límites; no toma por sí misma la decisión de retirada ni define la política.
Commerce: Payments v1 sigue funcionando
Este ejemplo es una síntesis del Atlas. Commerce ofrece POST /payments/v1/authorize y prepara POST /payments/v2/authorizations. Marca v1 como deprecated, mantiene su operación comprometida y explica diferencias de contrato, errores y tratamiento de identificadores. Una guía muestra qué deben cambiar Orders y los partners; no se presupone equivalencia automática entre payloads.
Los servicios conocidos migran, pero un partner llama v1 solamente al cierre mensual. Dos semanas sin requests suyos no prueban abandono. El equipo combina registros, contacto y revisión del proceso antes de proponer una retirada; tampoco convierte un header HTTP en sustituto de esa conversación.
Si aún no hay fecha, el aviso lo declara. Si más adelante se anuncia sunset, se comunica por separado. Un cliente atrasado puede requerir extensión explícita o afrontar el comportamiento publicado: no surge una respuesta universal de la palabra deprecated. Las obligaciones de refunds históricos siguen existiendo aunque todas las autorizaciones nuevas usen v2.
Costo, intención y evolución
Mantener adapters, pruebas duplicadas y soporte puede aumentar carga futura descrita por technical-debt, pero compatibilidad deliberada no es automáticamente deuda. Si el camino antiguo queda indefinidamente sin intención ni responsable, puede contribuir a architecture-erosion; una decisión vigente de conservarlo tiene otro significado.
evolvability conecta estabilidad para consumidores y capacidad del proveedor de cambiar sucesivamente. evolutionary-architecture incluye revisar y retirar decisiones, además de introducir nuevas. Deprecation ayuda a preparar ese movimiento, sin garantizar adopción ni hacer deseable el cambio permanente.
evolution-and-modernization conserva la distinción final: Deprecation señala y gestiona el abandono progresivo; Sunsetting organiza la retirada efectiva. Documentar, mantener operativa una capacidad y resolver su futuro son responsabilidades relacionadas que ninguna etiqueta resuelve sola.