Descontinuar uma função em uma biblioteca: avisar, documentar a substituta e remover no prazo definido

Objetivo

Remover ou alterar uma função, classe ou opção pública de uma biblioteca sem quebrar o código dos usuários entre versões consecutivas e sem manter o caminho antigo para sempre. Este é o equivalente, no lado da biblioteca, da descontinuação de um endpoint HTTP (com link), usando avisos e política de versões no lugar de cabeçalhos.

Pré-requisitos

Uma definição do que é público. A PEP 387 considera públicos os nomes, as posições e os tipos dos argumentos, os valores de retorno e as exceções lançadas, e exclui nomes com prefixo de sublinhado e tudo o que estiver documentado como privado; um nome não documentado não é automaticamente privado. Também é preciso uma política de ciclo de versões por escrito, porque a data de remoção é expressa em versões.

Passos

1. Publique primeiro a substituta, em uma versão que ainda suporte o caminho antigo sem alterações, de modo que a migração seja feita em uma única etapa.
2. Marque o caminho antigo na mesma versão ou na seguinte: um aviso em tempo de execução da categoria de descontinuação, uma nota na documentação de referência com a versão da descontinuação e a substituta, e uma entrada sob o título Deprecated no changelog.
3. Defina a versão de remoção por política, e não caso a caso. A PEP 387 estabelece que uma mudança incompatível deve passar pelo processo de descontinuação, que o ciclo anual implica pelo menos dois anos entre o aviso e a remoção e (desde uma mudança de 2025) que cinco anos é o preferido; a política do Django mantém um recurso descontinuado funcionando em todas as versões da série principal atual e o remove na próxima versão principal, ou uma versão depois, de modo que pelo menos duas versões de funcionalidades separem o aviso da remoção. Um projeto pequeno pode adotar "removido no mínimo na segunda versão de funcionalidades após o aviso".
4. Torne o aviso visível onde importa. O filtro padrão do Python ignora DeprecationWarning, exceto quando disparado diretamente por código em __main__; a documentação recomenda que os test runners exibam todos os avisos do código sob teste. Execute a suíte de testes da própria biblioteca com os avisos convertidos em erros, para que os usos internos do caminho antigo apareçam primeiro.
5. Prefira uma descontinuação leve (soft deprecation) quando for seguro manter o caminho antigo: a PEP 387 a descreve como documentada, testada, sem mais desenvolvimento e sem remoção agendada nem aviso.
6. Remova na versão anunciada, liste a remoção sob Removed no changelog e atualize a versão conforme a política de versionamento (uma versão major no Semantic Versioning).

Resultado esperado

Os usuários veem um aviso por ponto de chamada antigo, apontando para a substituta, e sabem em qual versão o caminho antigo desaparece; a biblioteca mantém cada shim por um número limitado de versões.

Limites e base de verificação

As políticas são citadas dos documentos do Python e do Django mencionados; um projeto com ciclo diferente precisa converter "duas versões" para o seu próprio prazo. Nenhum resultado de migração foi medido.