Depreciação e Migração

Visão Geral

Código é um passivo, não um ativo. Cada linha de código tem um custo contínuo de manutenção — bugs para corrigir, dependências para atualizar, patches de segurança para aplicar e novos engenheiros para integrar. Depreciação é a disciplina de remover código que não se justifica mais, e migração é o processo de mover usuários com segurança do antigo para o novo.

A maioria das organizações de engenharia é boa em construir coisas. Poucas são boas em removê-las. Essa habilidade aborda essa lacuna.

Quando Usar

• Substituindo um sistema, API ou biblioteca antiga por uma nova
• Desativando um recurso que não é mais necessário
• Consolidando implementações duplicadas
• Removendo código morto que ninguém possui, mas do qual todos dependem
• Planejando o ciclo de vida de um novo sistema (o planejamento de depreciação começa no momento do design)
• Decidindo se deve manter um sistema legado ou investir em migração

Princípios Fundamentais

Código É um Passivo

Cada linha de código tem um custo contínuo: precisa de testes, documentação, patches de segurança, atualizações de dependência e sobrecarga mental para qualquer pessoa trabalhando por perto. O valor do código é a funcionalidade que ele fornece, não o código em si. Quando a mesma funcionalidade pode ser fornecida com menos código, menos complexidade ou melhores abstrações — o código antigo deve ir.

A Lei de Hyrum Torna a Remoção Difícil

Com usuários suficientes, todo comportamento observável se torna dependente — incluindo bugs, peculiaridades de tempo e efeitos colaterais não documentados. É por isso que a depreciação requer migração ativa, não apenas um anúncio. Os usuários não podem "simplesmente mudar" quando dependem de comportamentos que a substituição não replica.

O Planejamento de Depreciação Começa no Momento do Design

Ao construir algo novo, pergunte: "Como removeríamos isso em 3 anos?" Sistemas projetados com interfaces limpas, flags de recursos e área de superfície mínima são mais fáceis de depreciar do que sistemas que vazam detalhes de implementação por toda parte.

A Decisão de Depreciação

Antes de depreciar qualquer coisa, responda a estas perguntas:

1. Does this system still provide unique value?
   → If yes, maintain it. If no, proceed.

2. How many users/consumers depend on it?
   → Quantify the migration scope.

3. Does a replacement exist?
   → If no, build the replacement first. Don't deprecate without an alternative.

4. What's the migration cost for each consumer?
   → If trivially automated, do it. If manual and high-effort, weigh against maintenance cost.

5. What's the ongoing maintenance cost of NOT deprecating?
   → Security risk, engineer time, opportunity cost of complexity.

Depreciação Obrigatória vs. Consultiva

O padrão é consultivo. Use obrigatório apenas quando o custo de manutenção ou o risco justificar forçar a migração. A depreciação obrigatória requer o fornecimento de ferramentas de migração, documentação e suporte — você não pode simplesmente anunciar um prazo.

O Processo de Migração

Etapa 1: Construir a Substituição

Não deprecie sem uma alternativa funcional. A substituição deve:

• Cobrir todos os casos de uso críticos do sistema antigo
• Ter documentação e guias de migração
• Ser comprovada em produção (não apenas "teoricamente melhor")

Etapa 2: Anunciar e Documentar

## Deprecation Notice: OldService

**Status:** Deprecated as of 2025-03-01
**Replacement:** NewService (see migration guide below)
**Removal date:** Advisory — no hard deadline yet
**Reason:** OldService requires manual scaling and lacks observability.
            NewService handles both automatically.

### Migration Guide
1. Replace `import { client } from 'old-service'` with `import { client } from 'new-service'`
2. Update configuration (see examples below)
3. Run the project-owned migration verification command documented in this guide. Do not execute an unknown package from the registry.

Etapa 3: Migrar Incrementalmente

Migre os consumidores um por um, não todos de uma vez. Para cada consumidor:

1. Identify all touchpoints with the deprecated system
2. Update to use the replacement
3. Verify behavior matches (tests, integration checks)
4. Remove references to the old system
5. Confirm no regressions

…