Pular para o conteúdo principal

Política de compatibilidade

A partir da versão 1.0.0, o Canopy compromete-se com uma retrocompatibilidade documentada dentro de uma linha de versão principal. Esta página é o contrato: descreve o que permanece estável, o que pode mudar e como funcionam as depreciações, para que os operadores possam planear atualizações sem surpresas.

A política aplica-se a 1.x. Uma futura linha 2.x poderá revisá-la; se assim for, um guia de migração será publicado com as notas de versão do 2.0.0.

O que está abrangido​

Esquema de base de dados (migrações Alembic)​

Dentro de 1.x:

  • As migrações são aditivas ou retrocompatíveis na atualização.
  • Novas colunas podem ser adicionadas a qualquer momento.
  • As colunas existentes não serão eliminadas sem passar por um ciclo de depreciação.
  • As colunas existentes não serão renomeadas sem um ciclo de depreciação (um renomeamento é implementado como adicionar-nova-coluna → preencher → deprecar-coluna-antiga → eliminar-na-próxima-versão-principal).
  • As alterações de tipo limitam-se ao alargamento (por exemplo, varchar(80) → varchar(255)); as alterações de estreitamento passam pela depreciação.
  • Os constraints de chave estrangeira não se tornarão mais restritivos (por exemplo, ON DELETE SET NULL a tornar-se ON DELETE CASCADE) sem um ciclo de depreciação.

Os operadores podem avançar com confiança; a migração automática no arranque do backend é segura para executar em dados de produção.

Metamodelo integrado​

Dentro de 1.x, o metamodelo que é incluído em backend/app/services/seed.py é estável:

  • As chaves de tipo de cartão integradas (Application, Initiative, BusinessCapability, etc.) não serão renomeadas nem removidas.
  • As chaves de campo integradas nesses tipos não serão removidas sem um ciclo de depreciação.
  • As chaves de tipo de relação integradas não serão renomeadas nem removidas sem um ciclo de depreciação.
  • Os subtipos predefinidos incluídos com os tipos integrados são estáveis.

As personalizações dos operadores (tipos de cartão personalizados, campos personalizados adicionados através da interface de administração, tipos de relação personalizados) são propriedade do operador e não estão abrangidas por esta política.

API REST (/api/v1/)​

Dentro de 1.x:

  • Os endpoints sob /api/v1/ não serão removidos sem um ciclo de depreciação.
  • Os nomes de campos de pedido e resposta existentes não serão renomeados sem um ciclo de depreciação.
  • Os tipos de campo não mudarão de forma incompatível (por exemplo, string → array).
  • Novos campos de pedido opcionais e novos campos de resposta não são alterações de ruptura e podem surgir em qualquer versão menor.
  • Novos endpoints não são alterações de ruptura e podem surgir em qualquer versão menor.
  • A semântica de autenticação (JWT Bearer, a forma do payload de /auth/login) é estável.
  • A semântica dos códigos de estado HTTP é estável para os caminhos de sucesso e erro documentados.

O comportamento para além da superfície documentada (cabeçalhos não documentados, texto de mensagens de erro internas, ordenação quando não é especificado sort_by) não está abrangido.

Chaves de permissão​

As chaves de permissão definidas em backend/app/core/permissions.py são estáveis dentro de 1.x. Novas chaves podem ser adicionadas; as chaves existentes não serão renomeadas nem removidas sem um ciclo de depreciação.

O conjunto de permissões concedidas por predefinição às funções inicializadas (admin, bpm_admin, member, viewer) pode mudar entre versões menores, com uma entrada no CHANGELOG. Os operadores que tenham personalizado as permissões das funções na sua implementação não são afetados.

Configuração (variáveis de ambiente)​

As variáveis de ambiente existentes documentadas em CLAUDE.md e README.md são estáveis dentro de 1.x. Novas variáveis podem ser adicionadas com valores predefinidos sensatos. Os valores predefinidos podem mudar com uma entrada no CHANGELOG quando a alteração é relevante para o operador (por exemplo, uma nova porta predefinida).

Segredos encriptados em repouso​

O marcador de prefixo enc: e a chave derivada de Fernet em backend/app/core/encryption.py são estáveis dentro de 1.x. Os operadores não precisam de voltar a encriptar segredos entre atualizações de versões menores.

Ciclo de depreciação​

Quando algo abrangido por esta política precisa de ser removido:

  1. Marcar como depreciado na versão menor N. A entrada no CHANGELOG inclui uma secção Deprecated que identifica a alteração. Para endpoints da API, a rota depreciada emite um cabeçalho de resposta Deprecation: true (RFC 8594) e um cabeçalho Sunset indicando o alvo mais cedo para remoção.
  2. Continuar a suportar na versão menor N+1. A remoção não pode ocorrer na mesma versão menor que a depreciação. A forma depreciada continua a funcionar.
  3. Remoção mais cedo possível na versão menor N+2 ou em 2.0 (o que ocorrer primeiro). A remoção é acompanhada de uma secção Removed no CHANGELOG e uma nota de migração.

Para alterações de forma de dados (migrações Alembic), aplica-se a mesma cadência N → N+1, expressa como adicionar-novo → preencher → eliminar-antigo.

O que não está abrangido​

Estes aspetos estão explicitamente fora do âmbito e podem mudar a qualquer momento:

  • A disposição interna do módulo Python sob backend/app/. As importações de app.models, app.services, etc. não fazem parte da API pública. Extensões ou scripts que dependam de importações internas devem fixar uma versão específica do Canopy.
  • A estrutura dos blobs JSONB armazenados nas tabelas integradas (fields_schema, section_config, attributes, lifecycle) para além do que é lido pela API REST documentada. A forma JSON em disco pode evoluir para suportar novas funcionalidades.
  • Internos do frontend: caminhos de ficheiros de componentes, assinaturas de props de componentes em frontend/src/, o conteúdo de frontend/src/types/index.ts e o estilo dos componentes MUI. Os operadores que utilizam o frontend incluído estão isolados; qualquer pessoa que incorpore componentes da árvore de código-fonte fica por sua conta.
  • Personalizações do metamodelo introduzidas pelo operador. Se adicionar um tipo de cartão ou campo personalizado através da interface de administração, é o responsável pela história de migração quando o alterar.
  • Dados de demonstração e inicialização (SEED_DEMO=true). O conjunto de dados de demonstração pode evoluir livremente entre versões.
  • Serviços de terceiros incluídos: versão do DrawIO, imagem Ollama incluída, versão do swagger-ui-dist incorporado. Estes podem ser atualizados a qualquer momento.
  • Comportamento com configurações não predefinidas que estejam explicitamente marcadas como experimentais nas entradas do CHANGELOG.

O que o 1.0.0 realmente muda​

Em comparação com a série 0.x, o 1.0.0 em si não é uma versão de funcionalidades — é o ponto a partir do qual os compromissos acima começam a aplicar-se. O código incluído no 1.0.0 é o mesmo código que foi incluído no 0.71.0, mais as melhorias na cadeia de fornecimento e as alterações no fluxo de contribuidores documentadas na entrada 1.0.0 do CHANGELOG.

As versões anteriores ao 1.0 não estavam abrangidas por esta política. As migrações entre versões 0.x podiam e incluíam eliminações de esquema, renomeamentos e alterações de ruptura no metamodelo. A partir do 1.0.0, essas alterações passam pelo ciclo de depreciação.