Estratégia de versões do Qiskit SDK
Os números de versão do Qiskit seguem o Versionamento Semântico.
O número de versão é composto por três componentes principais: as versões maior, menor e
de correção. Por exemplo, no número de versão X.Y.Z, X é a versão maior,
Y é a versão menor e Z é a versão de correção.
Mudanças que quebram a compatibilidade da API são reservadas para lançamentos de versão maior. O período mínimo entre lançamentos de versão maior é de um ano. Versões menores introduzem novos recursos e correções de bugs sem quebrar a compatibilidade da API, e são publicadas periodicamente (atualmente a cada três meses) somente para a versão maior atual. Versões de correção fornecem ajustes para bugs identificados na versão menor mais recente de cada série de lançamentos com suporte ativo (ou seja, a versão maior). Suportamos no máximo duas séries de lançamentos ao mesmo tempo, o que ocorre apenas durante o período de sobreposição após um novo lançamento de versão maior, descrito em mais detalhes abaixo.
Cronograma de lançamentos
Um cronograma provisório de lançamentos está incluído abaixo:
Para um cronograma de lançamentos atualizado, consulte a lista de marcos do projeto Qiskit no GitHub, que sempre conterá o plano de lançamento atual.
Com o lançamento de uma nova versão maior, a versão maior anterior passa a ter suporte por pelo menos seis meses apenas com correções de bugs, e um ano para correções de segurança. Durante esse período, apenas lançamentos de correção são publicados para essa versão maior. Uma versão de correção final é publicada quando o suporte é encerrado, e esse lançamento também documenta o fim do suporte para aquela série de versão maior. Uma janela de suporte mais longa é necessária para a versão maior anterior, pois isso dá aos consumidores downstream do Qiskit e aos seus usuários a oportunidade de migrar seu código. Bibliotecas downstream que dependem do Qiskit não devem elevar sua versão mínima exigida do Qiskit para uma nova versão maior imediatamente após seu lançamento, porque a base de usuários da biblioteca precisa de tempo para migrar para as novas mudanças de API. Ter uma janela de suporte estendida para a versão maior anterior do Qiskit dá aos projetos downstream tempo para garantir compatibilidade com a próxima versão maior. Projetos downstream podem oferecer suporte para duas séries de lançamentos ao mesmo tempo para dar aos seus usuários um caminho de migração.
Para fins de versionamento semântico, a API pública do Qiskit é considerada
qualquer módulo, classe, função ou método documentado que não seja marcado como privado
(com o prefixo de sublinhado _). No entanto, podem existir exceções explícitas para
APIs documentadas específicas. Nesses casos, essas APIs serão claramente documentadas
como interfaces que ainda não são consideradas estáveis, e um aviso visível ao usuário será
emitido ativamente em qualquer uso dessas interfaces instáveis. Além disso, em algumas
situações, uma interface marcada como privada é considerada parte da API pública.
Normalmente isso ocorre apenas em dois casos: ou uma definição de interface abstrata
onde subclasses devem substituir/implementar um método privado
como parte da definição de uma implementação da interface, ou métodos de baixo nível
de uso avançado que têm interfaces estáveis, mas não são considerados seguros para uso,
pois cabe ao usuário manter os invariantes de classe/segurança por conta própria
(o exemplo canônico disso é o método QuantumCircuit._append).
As versões de Python suportadas, a versão mínima suportada do Rust (para compilar o Qiskit a partir do código-fonte) e quaisquer dependências de pacotes Python (incluindo as versões mínimas suportadas das dependências) usadas pelo Qiskit não fazem parte das garantias de compatibilidade retroativa e podem mudar em qualquer lançamento. Apenas lançamentos de versão menor ou maior elevarão os requisitos mínimos para usar ou compilar o Qiskit (incluindo a adição de novas dependências), mas correções de patch podem incluir suporte para novas versões do Python ou outras dependências. Geralmente, a versão mínima de uma dependência só é aumentada quando versões mais antigas da dependência saem de suporte ou quando não é possível manter compatibilidade com o lançamento mais recente da dependência e a versão mais antiga.
Estratégia de atualização
Quando uma nova versão maior é lançada, o caminho de atualização recomendado
é primeiro atualizar para a versão menor mais recente na versão maior anterior.
Logo antes de uma nova versão maior, uma versão menor final será
publicada. Esse lançamento de versão menor final X.Y+1.0.0 é equivalente a
X.Y.0, mas com avisos e depreciações para quaisquer mudanças de API que foram
feitas na nova série de versão maior.
Por exemplo, imediatamente antes do lançamento da 1.0.0, uma versão 0.46.0 será publicada. A versão 0.46.0 será equivalente ao lançamento 0.45.0, mas com avisos de depreciação adicionais que documentam as mudanças de API feitas como parte do lançamento 1.0.0. Esse padrão será usado para quaisquer futuros lançamentos de versão maior.
Os usuários do Qiskit devem primeiro atualizar para essa versão menor final
para ver quaisquer avisos de depreciação e ajustar seu uso do Qiskit
antes de tentar um lançamento potencialmente disruptivo. A versão maior anterior
terá suporte por pelo menos seis meses para dar tempo suficiente
para a atualização. Um padrão típico para gerenciar isso é fixar a versão máxima para
evitar usar a próxima série de versão maior até ter certeza da compatibilidade.
Por exemplo, especificar qiskit<2 em um arquivo de requisitos quando a versão maior
atual do Qiskit é 1 garante que você está usando uma versão do Qiskit
que não possui mudanças que quebrem a API.
Limitar a versão abaixo da próxima versão maior
garante que você veja quaisquer avisos de depreciação antes de um
lançamento de versão maior.
Sem esse limite, o pip instala
a versão mais recente disponível por padrão.
O formato de serialização QPY é retrocompatível, de modo que um novo lançamento do Qiskit pode sempre carregar um
arquivo QPY gerado com uma versão anterior do Qiskit. No entanto, o formato não é compatível com versões futuras, portanto, em princípio, não é possível
carregar arquivos QPY gerados com uma versão mais recente do Qiskit usando uma versão mais antiga. Para facilitar a migração dos usuários entre lançamentos de versão maior, a função qiskit.qpy.dump() sempre suportará pelo menos uma versão sobreposta entre os lançamentos X.0.0 e X-1.Y.0 (onde Y é a última versão menor
dessa série). O parâmetro qiskit.qpy.dump(..., version=...) permitirá salvar arquivos no formato QPY que podem ser carregados por ambas as versões maiores a partir do novo
lançamento. Veja mais detalhes em RFC 0020.
Pré-lançamentos
Para cada lançamento de versão menor e maior, o Qiskit publica pré-lançamentos compatíveis com o PEP440. Tipicamente,
esses são candidatos a lançamento no formato X.Y.0rc1. Os lançamentos rc
terão uma superfície de API finalizada e são usados para testar um lançamento prospectivo.
Observe que quando um dos sufixos de pré-lançamento do PEP440 (como a, b ou pre) é
publicado, ele não tem as mesmas garantias que um lançamento rc, e é
apenas um lançamento de pré-visualização. A API pode mudar entre esses pré-lançamentos
e o lançamento final com esse número de versão. Por exemplo, 1.0.0pre1 pode ter
uma API final diferente de 1.0.0.
Pós-lançamentos
Se houver problemas com o empacotamento de um lançamento, um pós-lançamento pode ser
emitido para corrigir isso. Esses seguirão o formato X.Y.Z.1, onde o quarto
inteiro indica que é o primeiro pós-lançamento do lançamento X.Y.Z.
Por exemplo, o lançamento 0.25.2 do qiskit-terra (o nome legado do pacote Qiskit)
teve algum problema com a publicação do pacote sdist, e um pós-lançamento
0.25.2.1 foi publicado para corrigir esse problema. O código era idêntico, e
0.25.2.1 apenas corrigiu o problema de empacotamento do lançamento.
Como os contribuidores podem marcar depreciações
Consulte o guia de depreciação no repositório do Qiskit SDK para instruções sobre como adicionar depreciações ao código-fonte.