Quebrando alterações na API: como posso facilitar a transição para os usuários da biblioteca?

No passado, usei a maneira padrão de adicionar @Deprecatedanotações aos métodos de API que serão removidos em uma versão posterior.

Agora estou preparando uma versão principal para uma biblioteca, com muitas partes da API removidas e renomeadas.

Para facilitar a transição para usuários existentes, talvez seja útil se a nova versão da biblioteca puder ser usada lado a lado com a versão antiga.

Vantagens

• comutação dinâmica entre versões pode ser implementada
• os aplicativos podem voltar à versão anterior se forem encontrados erros na nova versão (útil na fase beta)

Para fazer isso, eu poderia simplesmente mover a nova versão da biblioteca para um novo pacote de com.mycompany.libraryparacom.mycompany.library.v2

Essa é uma prática comum ou existem outras recomendações para esse uso lado a lado das bibliotecas Java?

Fundo:

a biblioteca é um simples conversor de documentos. Portanto, além de um método convert (in, out), ele possui muitas propriedades de configuração e alguns manipuladores de eventos. Se eu fornecer uso lado a lado, os consumidores poderão instanciar e configurá-los dinamicamente:

if (useVersion2) {
  com.mycompany.library.v2.Converter c = new com.mycompany.library.v2.Converter();
  // configure and run
  c.setOption(...);
  c.convert(in, out); 
} else {
  com.mycompany.library.Converter c = new com.mycompany.library.Converter();
  // configure and run
  c.setOption(...);
  c.convert(in, out);
}

(pergunta movida de /programming/37192945/ )

Essa abordagem é bastante comum. Ele permite uma transição suave para uma nova API e uma evolução segura para novas implementações.

Obviamente, a abordagem se / então, como destacado por Laiv em sua resposta, tem algumas desvantagens. É entediante. É fácil esquecer ou confundir as coisas. Idealmente, o uso de invólucros, fábricas ou adaptadores poderia fornecer algumas alternativas mais agradáveis. Mas muitas vezes, quanto mais simples, melhor.

Martin Fowler e Pete Hogdson recentemente teorizaram sobre esse tópico em um excelente artigo no qual descrevem o que chamam de "padrões de alternância de recursos". Pode interessar-lhe diferentes estratégias de implementação - como o uso de um "roteador de alternância" - e os cenários de uso são descritos em detalhes completos.

Nota: pessoalmente, não sou encontrado em alternância de recursos. Vindo do mundo C ++, prefiro a alternativa fácil e robusta, usando alias de namespace e cláusulas para escolher, em tempo de compilação, a versão a ser usada. Mas é específico do idioma e, além disso, não permite configuração dinâmica, pois o recurso alterna. Então, como dito, às vezes, quanto mais simples, melhor ;-)

A biblioteca de atualização é um ótimo exemplo disso. Não faz muito tempo que eles introduziram uma versão estável 2, que é realmente boa, mesmo que tenha trazido algumas quebras.

Algumas das coisas notáveis ​​que eles fizeram foram:

1. A nova API tem muito valor e aborda muitas das deficiências da versão mais antiga. Isso significa que sua nova API deve ser muito boa. Não apenas em termos de como funciona, mas também faz com que pareça agradável e fácil, se isso já foi um problema.

2. A versão beta da nova API foi lançada, permitindo que os usuários aprendam as mudanças desde o início e até forneçam bons comentários.

3. A transição também não foi tão dolorosa. Eles introduziram o número da versão no próprio nome do pacote, o que significa que algumas alterações exigiam apenas a modificação das instruções de importação. Sim, algumas classes foram removidas e outras introduzidas, mas não parecia muito drástico. Isso também depende de como o usuário organizou sua base de código, que está parcialmente fora do escopo do desenvolvedor da API.

Além disso, os guias de migração são preferidos. Retrofit, sendo uma biblioteca popular, muitos artigos sobre isso estão disponíveis online.

Não acho que dividir código if/elseseja uma boa abordagem.

Pense a longo prazo. O que você vai fazer com outras versões? )

Como o código do usuário pode acabar sendo ao longo do tempo?

Para versões secundárias ou revisões, é esperado manter a compatibilidade. O @Deprecated vem com um comentário pedindo ao desenvolvedor que não use esse código. Também sugere que componente / método / classe deve ser usado. Finalmente, muitos deles informam que o código descontinuado não será suportado em versões posteriores. Ou talvez não seja suportado (eles ainda não sabem).

No entanto, em novas versões (grande alteração na reformulação) não faz muito sentido manter o código obsoleto, pois dificulta a manutenção. O código legado também pode ser afetado pelas alterações feitas. Diretamente ou não.

Também deixa claro o uso. Mesmo se o código descontinuado for anotado.

Se o seu caso for realmente uma grande mudança ou reformulação, prefiro incentivar / forçar os usuários a migrar para o novo recurso.

Se uma nova lib parecer instável, o usuário poderá fazer o downgrade da dependência e permanecer nela até que novos bugs da lib sejam resolvidos.

Como desenvolvedor, espero alterações de uma versão para outra. Se eu decidir usar o novo, aceito aceitar essas mudanças.

No pior cenário, posso voltar ao anterior.

Eu não colocaria expressões como 'é temporal'. Porque todos sabemos como isso acaba ...

Em vez de impedir que o usuário caia em tais declarações que acabam em código difícil de ler e difícil de manter