Deprecation policies: comunicando e gerenciando fim de suporte

1. Fundamentos de uma Política de Deprecação

1.1. Definição e objetivos

Uma política de deprecação é o conjunto de regras, prazos e procedimentos que uma organização adota para comunicar e gerenciar o fim de suporte de um componente de software. Na arquitetura de software, planejar o fim de suporte é tão crítico quanto planejar a introdução de uma nova funcionalidade. Sem uma política clara, consumidores de APIs, bibliotecas ou serviços podem ser pegos de surpresa, gerando incidentes de produção, falhas de segurança ou paradas não planejadas.

1.2. Ciclo de vida de um componente

Todo componente arquitetural passa por estágios: introdução, maturidade, deprecação e fim de vida (EOL). A deprecação é o aviso formal de que o componente está caminhando para o EOL. Nessa fase, ainda há suporte, mas espera-se que os consumidores migrem para a alternativa recomendada.

1.3. Impactos arquiteturais de uma deprecação mal gerida

Uma deprecação mal gerida gera:
- Dívida técnica: versões antigas continuam sendo usadas, acumulando complexidade.
- Acoplamento excessivo: consumidores presos a versões obsoletas dificultam evoluções.
- Riscos de segurança: versões deprecadas podem não receber patches críticos.

2. Estruturando uma Política de Deprecação Eficaz

2.1. Critérios para declarar deprecação

Uma funcionalidade deve ser deprecada quando:
- Uma alternativa madura e estável existe.
- A versão atual apresenta riscos de segurança conhecidos.
- O componente atingiu o fim de seu ciclo de vida planejado.

2.2. Prazos e fases

A política deve definir fases claras:

Fase                  Duração        Ação esperada
Soft deprecation      30-90 dias     Notificação inicial, sem bloqueios
Hard deprecation      90-180 dias    Headers de aviso, logs de alerta
End-of-life (EOL)     Indeterminado  Componente removido ou bloqueado

2.3. Documentação e versionamento da política

A política deve ser pública, versionada e associada a um roadmap. Exemplo de entrada em changelog:

## [2025-03-15] - Deprecação da API v1
- Status: Soft deprecation
- Alternativa: API v2 (documentação em /docs/v2)
- Prazo EOL: 2025-09-15
- Motivo: Substituição por arquitetura baseada em eventos

3. Estratégias de Comunicação com Consumidores

3.1. Canais de notificação

Múltiplos canais aumentam a chance de os consumidores tomarem ciência:
- E-mail para contatos técnicos cadastrados.
- Dashboard de status do serviço.
- Webhooks para consumidores que se inscreveram.
- Changelogs automatizados no repositório.

3.2. Headers e metadados em APIs (RFC 8594)

A RFC 8594 define headers HTTP específicos para comunicar deprecação:

HTTP/1.1 200 OK
Content-Type: application/json
Sunset: Sat, 15 Sep 2025 23:59:59 GMT
Deprecation: true
Warning: 299 - "API v1 will be removed. Use v2."

O header Sunset indica a data exata de remoção. O Deprecation sinaliza que a versão atual está deprecada. O Warning fornece uma mensagem legível.

3.3. Comunicação proativa vs. reativa

A comunicação proativa inclui:
- Webinars de migração.
- Documentação de transição com exemplos comparativos.
- Suporte assistido para grandes consumidores.

A comunicação reativa (apenas headers e logs) deve ser evitada para consumidores críticos.

4. Gerenciamento Técnico da Transição

4.1. Roteamento e versões

A coexistência de versões pode ser feita por:
- URI: /api/v1/recurso vs /api/v2/recurso
- Header de versão: Accept: application/vnd.empresa.v1+json
- Content negotiation: baseada no corpo da requisição

Exemplo de configuração de roteamento:

# Configuração de proxy reverso (NGINX)
location /api/ {
    if ($http_accept ~ "v1") {
        proxy_pass http://backend-v1;
    }
    if ($http_accept ~ "v2") {
        proxy_pass http://backend-v2;
    }
}

4.2. Ferramentas de monitoramento

Métricas essenciais:
- Taxa de uso de endpoints deprecados (por versão, por consumidor).
- Alertas quando um consumidor excede o prazo de sunset sem migrar.
- Logs de warning para chamadas deprecadas.

4.3. Automação de migração

Scripts de migração assistida podem ser fornecidos:

# Script de migração de cliente API v1 para v2
# Uso: python migrate.py --old-url https://api.exemplo.com/v1 --new-url https://api.exemplo.com/v2
import requests
import json

def migrate_endpoint(endpoint, payload):
    # Tenta chamar v2 primeiro
    response = requests.post(f"https://api.exemplo.com/v2/{endpoint}", json=payload)
    if response.status_code == 200:
        return response.json()
    # Fallback para v1 com warning
    print("WARNING: v1 será removida em 2025-09-15")
    response = requests.post(f"https://api.exemplo.com/v1/{endpoint}", json=payload)
    return response.json()

Feature toggles permitem desligar gradualmente uma versão para consumidores específicos.

5. Tratamento de Exceções e Casos Complexos

5.1. Extensões de prazo para consumidores críticos

Para consumidores com contratos enterprise ou sistemas legados críticos, extensões de prazo podem ser negociadas, mas com condições:
- Taxa adicional.
- Compromisso de migração em data acordada.
- Suporte limitado a patches de segurança.

5.2. Deprecação de funcionalidades internas vs. APIs públicas

Em microsserviços, a deprecação de uma funcionalidade interna (ex: endpoint de um serviço consumido por outro serviço interno) pode ser mais agressiva, pois os times têm controle sobre os consumidores. Já APIs públicas exigem prazos maiores e comunicação mais robusta.

5.3. Rollback e reversão

Um plano B deve existir caso a migração cause incidentes:
- Manter a versão antiga ativa por um período de contingência.
- Feature toggle para reativar a versão antiga rapidamente.
- Documentação do procedimento de rollback.

6. Exemplos Práticos e Padrões de Implementação

6.1. Exemplo de política em API REST

Política completa para uma API REST:

POLÍTICA DE DEPRECAÇÃO - API de Pagamentos
Versão: 2.0 | Data: 2025-01-01

1. Soft deprecation (dias 0-90):
   - Headers Sunset e Deprecation adicionados.
   - Logs de warning no servidor.
   - Notificação por e-mail aos consumidores.

2. Hard deprecation (dias 91-180):
   - Respostas incluem Warning header.
   - Dashboard de status marca versão como "em descontinuação".
   - Novos consumidores não podem usar a versão.

3. End-of-life (após dia 180):
   - Versão retorna 410 Gone.
   - Redirecionamento automático para v2 (se possível).

6.2. Exemplo para bibliotecas/SDKs

Para SDKs, a política pode ser:

POLÍTICA DE DEPRECAÇÃO - SDK Java v3
Versão mínima suportada: Java 11
Breaking changes: apenas em major versions

Cronograma:
- v3.0: lançamento (2024-01)
- v3.1: deprecação de métodos obsoletos (2024-06)
- v4.0: remoção de métodos deprecados (2025-01)

6.3. Padrão de sunset period

Prazos recomendados baseados em maturidade:

Maturidade do ecossistema     Sunset period
Baixa (startups, experimentos)  90 dias
Média (produtos estabelecidos)  6 meses
Alta (sistemas críticos, gov)   12 meses ou mais

7. Métricas e Aprendizado Contínuo

7.1. KPIs de sucesso

Indicadores para avaliar a eficácia da política:
- Taxa de adoção da nova versão: percentual de consumidores migrados antes do EOL.
- Tempo médio de migração: dias entre o aviso e a migração completa.
- Incidentes pós-deprecação: número de chamadas para versão removida.

7.2. Post-mortem de deprecações

Após cada ciclo de deprecação, conduza uma revisão:
- O que funcionou na comunicação?
- Houve consumidores que não migraram a tempo? Por quê?
- Os prazos foram adequados?

7.3. Evolução da política

A política deve ser revisada periodicamente. Conforme o ecossistema amadurece, prazos podem ser ajustados (ex: reduzir de 12 para 6 meses quando a adoção de novas versões é rápida). A transparência sobre essas mudanças é essencial.

Referências