Quanto tempo esperar antes de excluir um método obsoleto? [fechadas]

Estou mantendo uma API pública e preciso descontinuar um método.

Existe uma regra geral sobre quantos meses / anos / versões antes da exclusão eu devo descontinuar um método?

No mínimo, você deve manter os métodos obsoletos em uma versão antes de removê-los, o que parece óbvio quando escrevo. Não acho que exista um tempo máximo, mas se você nunca os remover, a depreciação se tornará um pouco inútil.

As principais versões são um bom momento para remover métodos obsoletos. Versões secundárias normalmente não devem conter alterações recentes. Como o cHao observou nos comentários, a depreciação não implica necessariamente que haverá uma eventual remoção; portanto, se você planeja remover coisas após a depreciação, observe explicitamente isso e forneça algumas orientações sobre a linha do tempo.

Isso depende apenas do tipo de estabilidade que você deu aos seus usuários e quanta dor você deseja causar aos seus usuários.

Idealmente, sua API usa semver para que qualquer alteração de quebra faça com que o número da versão principal seja incrementado. Na prática, é desejável fazer isso quase nunca. Se sua API for instalada por meio de algum gerenciador de pacotes, convém criar um novo nome de pacote após uma alteração de última hora, para que uma atualização simples não cause conflitos (por exemplo, myapi2 v2.123.4vs myapi3 v3.2.1). Isso pode ser desnecessário se o seu gerenciador de pacotes suportar dependências de versão mais restritas (por exemplo, uma especificação de dependência como ~v2.120essa não inclui v3.*), mas nomes de pacotes diferentes têm a vantagem de que versões incompatíveis podem ser usadas lado a lado com muita facilidade. Mesmo ao usar o semver, pode ser sensato ter um período de reprovação.

Semver nem sempre é aplicável. Então é mais importante comunicar uma política de estabilidade clara. Por exemplo:

• Recursos experimentais podem ser removidos sem aviso prévio.
• Os recursos podem ser removidos por razões de segurança a qualquer momento.
• Outros recursos serão removidos apenas
  • … Depois de ter sido descontinuado em uma versão lançada
  • ... em que essa versão tenha pelo menos três meses
  • … E será marcado por um solavanco na versão principal.

Essas políticas funcionam particularmente bem quando você tem lançamentos regulares, para que haja um período de depreciação claro, por exemplo, um ano.

Além de marcar qualquer parte da API como descontinuada, você deve tornar a descontinuação amplamente conhecida. Por exemplo:

• Tenha uma seção em seu registro de alterações sobre direções e descontinuações futuras.
• Transmita sua intenção de desaprovar antes de executá-la e ouça a comunidade para ver se há objeções substanciais.
• Comunique quais benefícios virão dessas mudanças. Dependendo da sua base de usuários, boletins, apresentações, postagens em blogs ou press releases podem ser a mídia apropriada. Dando uma volta “estamos criando um novo recurso incrível! (que requer que esse recurso antigo amplamente usado seja removido) ”é um pouco menos frustrante do que remover um recurso sem contexto.

Quanto ao período exato de descontinuação escolhido, verifique primeiro se você precisa honrar algum contrato de suporte com seus usuários. Esses contratos podem exigir que você mantenha a compatibilidade por algum período. Caso contrário, considere qualquer impacto a jusante. Tente mudar menos rapidamente do que os usuários downstream, para que eles possam passar por um ciclo de depreciação próprio. Os usuários downstream levarão algum tempo para se adaptarem às suas alterações, portanto, você nunca deve ter um período de descontinuação menor que um mês.

Idealmente, você esperaria até que ninguém mais estivesse usando o método descontinuado. Considerando que você está usando uma API pública, isso é fácil de rastrear, mas você pode esperar muito tempo.

em 2015, o Google teve um problema semelhante com a API stlport em seu sistema operacional Android. Eles o preteriram e queriam removê-lo, mas muitos aplicativos ainda o estavam usando. Eles encontraram uma solução inteligente:

Essencialmente, eles adicionaram um sono de 8 segundos () durante a inicialização de qualquer aplicativo que ainda usasse a API com uma mensagem de log apropriada para os desenvolvedores. Um mês depois, eles dobraram para 16 segundos. outro mês depois, eles puderam remover com segurança a interface da API porque não havia mais ninguém usando ela.

Essa pode ser uma maneira muito eficaz de fazer isso. O único problema real é se sua API é muito antiga e usa ativamente consumidores que não são mais suportados ativamente. Infelizmente, você provavelmente não conseguirá consertar esses consumidores, mas nesse momento não poderá fazer muito mais do que excluir o método e interromper o consumidor.

O tempo mínimo para fornecer métodos descontinuados depende dos ciclos de desenvolvimento de programas usando sua API. Como uma estimativa, um ano deve ser suficiente.

Quanto ao tempo máximo antes de você remover os métodos obsoletos, eu argumentaria que não existe. Não importa quanto tempo você espere, a remoção de um método descontinuado sempre quebrará alguma coisa. Alguns programas que usam a API descontinuada não são mantidos ativamente e a quebra de compatibilidade significará o fim da vida útil desses programas.

Sugiro que você remova os métodos obsoletos ao obter algo com a remoção :

• Foi detectado um bug que afeta métodos preteridos especificamente
• você está prestes a refatorar o código e a manutenção de métodos obsoletos exigiria um esforço significativo
• você está otimizando a estrutura interna da sua biblioteca e os métodos descontinuados não se encaixam mais.

A remoção de métodos descontinuados apenas porque foram descontinuados por X meses / anos ou porque você está lançando uma nova versão significa prejudicar arbitrariamente a compatibilidade sem uma boa razão.

Primeiro você deve considerar se deseja obsoleto ou obsoleto.

Descontinuado deve ser usado para métodos que são de alguma forma prejudiciais: segurança, desempenho, resultados incorretos. Você quer se livrar deles de forma relativamente rápida, não mais do que 2 versões principais e passou pela 3ª. Para problemas significativos o suficiente, o uso obsoleto pode ser excluído na próxima versão secundária.

Obsoleto é para coisas que são menos úteis por algum motivo, por exemplo, retorna menos informações ou não funciona tão bem, não inclui tantas opções e assim por diante. Eles podem permanecer indefinidamente, mas devem estar presentes, no mínimo, na próxima versão principal.

A resposta depende do tipo de serviço que você está oferecendo aos seus clientes.

Em um extremo, existem erros no Windows.h da era Win 3.1 que se propagaram por duas décadas porque a Microsoft acreditava fortemente na compatibilidade com versões anteriores.

Por outro lado, muitos aplicativos da Web removem recursos sem fornecer um aviso de descontinuação.

Quanto seus clientes estão pagando pelo seu software geralmente importa, assim como a linha de trabalho deles. Os cientistas de pesquisa geralmente estão mais dispostos a aceitar a depreciação como parte da marcha do progresso do que, digamos, banqueiros ou a FAA.

Eu trabalhei para uma empresa que desenvolvia software para uso interno. Apoiei muitos grupos ao longo dos anos. Um grupo tinha uma mentalidade de "nunca remover nenhum recurso". Eles precisavam voltar aos arquivos de 5 a 10 anos atrás e fazer análises neles em escalas de tempo muito rápido para que os desenvolvedores colocassem os recursos de volta. A atitude de um grupo era "garantir que todas as depreciações estejam nas notas do patch, então nós pode encontrá-los mais tarde. " No meio, tínhamos um grupo cuja regra era "Os recursos devem ser descontinuados por pelo menos uma versão com um aviso impresso, se usados ​​antes de removê-los". Esse grupo tinha um conjunto de testes que cobria os recursos de que eles precisavam. Sempre que lançamos uma nova versão, eles rapidamente executavam seu conjunto de testes para verificar se alguma das deprecações causava problemas.

Estou mantendo uma API pública e preciso descontinuar um método.

Por que você tem que fazer isso? É porque existe uma nova maneira brilhante de fazer as coisas, então o método antigo agora é desencorajado, mas ainda funciona bem? Ou o método antigo realmente precisa seguir porque as coisas mudaram fundamentalmente?

• Se o método antigo não está causando problemas reais e pode permanecer por aí, ele também pode. Se não está quebrado, não conserte.Você realmente precisa removê-lo? Talvez marque-o como obsoleto e inclua na documentação que outro método pode ser mais eficiente, ou o que for, mas provavelmente é bom deixá-lo no lugar.

• Se o método antigo realmente precisar seguir, porque está causando dores de cabeça na manutenção ou simplesmente porque não faz mais sentido devido a outras alterações, monitore seu uso e comunique claramente a depreciação aos clientes. Dê a eles uma data clara após a qual o método será removido. (Idealmente, não o remova imediatamente nesta data: aguarde até que ninguém ainda o esteja usando antes de removê-lo. Pode ser necessário ir mais cedo, se estiver realmente causando problemas, mas pelo menos aguarde o uso pouco.)

• Se o método antigo estiver causando problemas de segurança, talvez seja necessário mover-se mais rápido que isso, possivelmente até removê-lo sem aviso, mas você deve documentar essa alteração em algum lugar muito visível e também retornar mensagens sensíveis aos clientes que tentarem usar o método antigo.

(Os segundos dois pontos principais são bem abordados em outras respostas, mas acho que o primeiro é novo.)

Para um projeto público, remova-o somente se e somente se for necessário.

Quando você faz a remoção desnecessária da API, está custando dinheiro a empresas e prestadores de serviços de forma que você não pode nem calcular devido à rotatividade dispendiosa.

Deseja que empresas e programadores independentes parem de usar seu projeto? Quebre as coisas o suficiente, quando você não for essencial e você estará naquele barco em pouco tempo.

deprecation != eventual_removal. Se uma API é perigosa, você a remove. Se estiver velho, deixe-o e documente sua substituição.