Migração versão e depreciação sem surpresa

Explicitar o compromisso público

Um contrato público define o que consumidores podem esperar de uma interface. Versionar identifica a evolução desse compromisso; migrar prepara dados e consumidores para uma mudança; depreciar comunica que uma opção será retirada, com alternativa e condições conhecidas. O changelog apresenta o impacto da entrega. Esses instrumentos se complementam. Um número novo, sozinho, não converte uma alteração incompatível em uma experiência previsível.

No versionamento semântico, uma API pública declarada orienta a distinção entre correção compatível, funcionalidade compatível e mudança incompatível. As regras dependem dessa declaração e da fase do projeto [S10, especificação sobre API pública e incrementos de versão]. Neste capítulo, supomos uma API estável 1.0.0 para estudar decisões; não afirmamos que a versão real do laboratório já ofereça estabilidade de produção. A resposta pública atual de cada caso é {id,titulo,descricao}.

Plano de alteração preenchido

Imagine a proposta futura de substituir o nome descricao por resumo na resposta. A implementação atual não faz essa mudança. Um consumidor que lê descricao perderia conteúdo se o campo desaparecesse sem preparação. Primeiro investigamos os consumidores e seus contratos, incluindo clientes que rejeitam campos desconhecidos. Acrescentar um campo também precisa de análise de compatibilidade nesse contexto.

Tratar dados e código em conjunto

• Descreva exatamente a mudança de entrada, saída e efeito. Faça uma lista dos consumidores e das suposições que podem ser invalidadas.
• Escolha uma estratégia: manter compatibilidade temporária, oferecer uma nova interface ou coordenar a troca. Defina como verificar cada opção.
• Prepare a migração com dados artificiais, preservando identificadores e regras relevantes. Compare conteúdo antes e depois para detectar perdas.
• Comunique a alternativa e um prazo condizente com o contexto. Datas D0 e D30 são marcos do exercício, não anúncios ou compromissos reais.
• Monitore adoção com sinais necessários e proporcionais. Defina como agir quando ainda houver consumidores dependentes da interface antiga.
• Ensaie retorno ou correção adiante conforme a reversibilidade. Depois da retirada, confirme o comportamento dos consumidores e atualize instruções e testes.

Uma comunicação que ajuda a agir

Um aviso preenchido para o cenário poderia dizer: a interface futura passará a usar resumo; a versão atual permanece disponível durante a transição acordada; consulte o exemplo de adaptação e informe impedimentos antes da revisão D30. A decisão final considerará a adoção observada e os riscos pendentes. Um aviso como melhoramos a API não oferece a quem mantém um consumidor a informação necessária para agir.

O changelog da versão deve relacionar comportamento anterior, comportamento novo, pessoas afetadas e ação exigida. Se houver migração de dados, inclui o roteiro e o limite do retorno. Na prática atual, a idempotência da reserva permanece em memória: reiniciar o processo elimina o histórico de chaves. Essa limitação precisa continuar visível durante qualquer mudança de versão; um número maior não amplia automaticamente a garantia de efeito único [S15, seção sobre identificadores de solicitação e repetição segura].

Erros e decisão de avanço

A mudança avança quando compatibilidade, migração, comunicação e recuperação possuem resultados aceitáveis no escopo definido. Riscos residuais não impeditivos precisam de aceitação responsável. Um consumidor obrigatório ainda sem alternativa ou uma migração com perda inexplicada impedem a retirada. Um prazo vencido é um dado para a decisão, não uma demonstração de que a transição terminou.

Exercício e solução

Dados: a rota antiga atende dois consumidores obrigatórios; um já usa a nova, o outro depende de um campo removido e ainda não recebeu exemplo de adaptação. O prazo proposto termina amanhã. Planeje a decisão e escreva duas linhas do changelog.