Versão 1.0.0-alpha.1mais recente
Capítulo 2.28
Lançar a sua extensão
Como um plugin ou pacote passa de uma compilação bem-sucedida para as unidades que o executam, e como volta a sair. Versões, revisão de lançamento, canais e instalações, assinatura, aprovações de alterações, o registo de identidade de entrega, migrações, reversão e descontinuação de uma versão.
Esta página foi traduzida por IA a partir do original em inglês. Em caso de dúvida, a página em inglês serve de referência. Ler esta página em inglês

O Cold chain 0.4.0 foi a primeira versão nossa que pediu mais do que a anterior. Acrescentou o envio de correio e um endereço externo, para alertas de contentores refrigerados. A compilação estava verde, os testes passaram nos três ramos sintéticos, e mesmo assim ficou dois dias no espaço de desenvolvimento enquanto duas pessoas liam o que pedia e uma terceira aprovava o endereço. É assim que se pretende que seja lançar uma versão no Nexus: o código é a parte fácil, e as evidências e as aprovações são a versão.
Este capítulo abrange tudo o que se passa entre uma compilação verde e uma versão em execução para todas as unidades, bem como as formas de recuar. O próprio percurso de promoção, do espaço de desenvolvimento para staging, para uma unidade piloto e para todas as unidades, é apresentado no capítulo 2.24, Construir uma vertical personalizada de ponta a ponta, e não repetirei aqui as suas barreiras. Uma regra enquadra tudo. A implementação faz-se apenas através dos canais de lançamento da instalação. Não existe porta lateral para uma correção urgente, e ninguém edita manualmente uma imagem em execução.
Versões
Num lançamento de pacote movem-se três números de versão, e compensa mantê-los separados na sua cabeça.
| O quê | Onde se encontra | Exemplo | Regra |
|---|---|---|---|
| O plugin | version em nexus.manifest.json |
0.4.0 |
Versão semântica; é permitido um sufixo de pré-lançamento como -rc.1 |
| O pacote | version em pack.json |
0.4.0 |
Move-se com as lentes, as palavras e os clusters do pacote |
| O modelo de conhecimento | A versão própria do modelo | 1.3 a 1.4 |
Move-se apenas através de um pedido de alteração do grafo |
Uma compilação de desenvolvimento tem um sufixo, 0.4.0-dev, até chegar a staging. Mantenha iguais as versões do plugin e do pacote quando são lançados em conjunto; isso evita, em cada revisão de versão, uma discussão sobre a que número pertencem as evidências.
Duas outras versões são fixadas em vez de escolhidas. A versão do modelo base do pacote (domain-pack@1.6.0 para o Cold chain) é fixada quando o pacote é criado e só se move como uma alteração revista. O SDK (kit de desenvolvimento de software) é instalado numa versão exata, nunca num intervalo, para que a mesma compilação dê o mesmo resultado no mês seguinte:
npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0As skills do Skills Engine também têm versões, e comportam-se de forma diferente. Cada versão publicada é fixa, e live, canary e shadow são etiquetas em versões. Reverter move uma etiqueta, e as execuções já em curso terminam na versão com que começaram.
Antes de pedir uma revisão: o manifesto
A página Manifesto e permissões compara o que esta versão declara com a versão anterior: os seus âmbitos, os seus armazenamentos, os seus endereços de saída e o seu perfil de sandbox. Leia-a antes de pedir a alguém que reveja, porque indica exatamente o que será pedido aos revisores que aceitem.
Uma versão que pede mais do que o seu manifesto declarava antes fica retida onde está, com MANIFEST_SCOPE_WIDENED, até que dois revisores aceitem o manifesto alargado. Um endereço externo precisa também da aprovação de quem gere os endereços externos no cliente; essa aprovação é dada por um prazo fixo, e a nossa foi por 12 meses. Tem duas formas de avançar: remover as linhas ou pedir revisão. A página oferece ambos os botões.
Cada linha dessa página é aplicada em tempo de execução, não apenas revista. Cada chamada de ferramenta é verificada face aos âmbitos declarados, um endereço externo é bloqueado a menos que esteja listado, e o perfil de sandbox não permite qualquer outra rede. Um plugin que tente chegar a algo que não declarou é recusado, e a única solução é uma nova versão que o declare.
Revisão de lançamento
A página Revisão de versão reúne numa só tabela as evidências de uma versão, para um revisor que não seja o autor.
| Evidência | O que mostrou para a 0.4.0 |
|---|---|
| Testes | 66 de 66, em três ramos sintéticos |
| Verificações de qualidade | A documentação e o código estão de acordo |
| Política | Cada lente apenas restringe; campos pessoais desativados por predefinição |
| Assinaturas | Imagem e pacote assinados pelo pipeline |
| Diferença de âmbitos | Acrescenta o envio de correio e um endereço externo, com a respetiva aprovação |
| Compatibilidade | A versão da plataforma e a versão do pacote base com que foi testada |
| Alteração do modelo | A execução de teste do pedido de alteração do grafo: 1284 ligações renomeadas, nada removido |
Abaixo da tabela encontram-se os comentários sobre a alteração e a proveniência: que pipeline a compilou, a partir de que alteração, o digest da imagem e o modelo base. Os revisores aprovam com a sua passkey. Dois revisores que não sejam o autor aprovam, e o pipeline move então a versão para staging. O autor nunca conta como revisor, e uma tentativa é recusada com NEEDS_SECOND_PERSON. Um pedido de revisão caduca ao fim de 3 dias.
Responda às perguntas dos revisores nos comentários, não numa janela de chat. Durante a nossa revisão, o nosso responsável de conformidade perguntou porque é que o montante da reclamação estava classificado como comercial, e o segundo revisor pediu o plano de reversão para a alteração do modelo. Ambas as respostas fazem agora parte do registo da versão, que é onde o próximo revisor irá procurar.
Aprovações da política de alterações
A revisão de versão abrange a versão como um todo. O bloco changePolicy no manifesto vai mais longe: indica que classes de alteração aos componentes implementáveis do seu plugin precisam de aprovação, e de quantas pessoas.
"changePolicy": {
"enabled": true,
"classes": ["website", "bff", "migration"],
"approvals": { "website": 1, "bff": 1, "migration": 2 }
}As três classes são website (a aplicação web), bff (o backend for frontend) e migration (uma migração de base de dados). Cada classe indicada em classes tem de ter a sua própria contagem em approvals, de 1 a 10. Uma classe que omita fica sem governação, e o esquema obriga a escrevê-lo como uma escolha em vez de lá chegar por omissão. Pedimos duas aprovações para migrações porque uma migração é a única alteração difícil de desfazer.
As aprovações são contadas em pessoas distintas, e o proponente nunca é uma delas. Vale a pena conhecer as regras que o sustentam, porque cada uma tem uma recusa:
- Uma aprovação da pessoa que propôs a alteração é recusada com
TRUST_APPROVAL_SELF_APPROVAL. - Uma pessoa que não pode de todo fazer uma alteração dessa classe é recusada com
CHANGE_CLASS_NOT_PERMITTED. - Quando qualquer commit da alteração está assinado pela identidade de agente da organização, o quórum é o mínimo habitual mais um, e o voto do próprio agente não conta.
- Cada aprovação regista a diferença e o head que viu. Se a alteração mudar após a última aprovação, a integração é recusada com
HASH_MISMATCH, e as aprovações têm de ser recolhidas novamente para o novo conteúdo.
Essa terceira regra é importante se desenvolver com uma ferramenta de programação com IA (inteligência artificial), como descreve o capítulo 2.26, Desenvolver com ferramentas de programação com IA. O trabalho escrito por um agente precisa de mais uma aprovação humana do que o trabalho escrito por uma pessoa. Planeie em conformidade.
Assinatura e verificação
Cada imagem e cada pacote são assinados pelo pipeline que os compilou, e uma imagem assinada é uma das barreiras de entrada em staging. Um espaço de desenvolvimento executa apenas imagens assinadas desde o início. Na Enterprise, um administrador define cada namespace para registar imagens não assinadas ou para as recusar, e passa os namespaces para recusa um de cada vez, para que a produção acabe por executar apenas imagens que o pipeline compilou e assinou. A assinatura faz parte da compilação, não é algo que se acrescenta antes de um lançamento.
A regra que atravessa tudo isto é que uma assinatura que falha é uma recusa, nunca um aviso. Uma verificação que recebe SIG_INVALID para. Não recorre à versão não assinada nem continua com uma nota num registo, porque um aviso num registo de compilação é uma aprovação para todos os que não o leram.
A mesma regra aplica-se a tudo o que entrega em suporte físico. Um pacote selado para um cliente air-gapped é verificado face à sua chave pública antes de qualquer coisa ser desempacotada, e o capítulo 2.25, Desenvolver para cada edição, mostra o comando.
Identidade de entrega
Um plugin é entregue através de vários elementos que têm, cada um, um nome: os seus repositórios, uma chave de assinatura, um namespace de implementação, um prefixo de registo, um esquema de base de dados, um conjunto de domínios e uma política de alterações. Qualquer um deles é um ponto onde dois plugins podem colidir, ou onde um plugin pode divergir. A identidade de entrega é um registo assinado por plugin que os contém a todos, para que cada verificação no percurso de lançamento leia a mesma resposta e recuse perante uma discrepância.
Contribui com a sua parte através do manifesto e de nada mais: schema, db, domains, changePolicy e o URL do repositório. A plataforma completa o registo com o resto e assina-o. Nunca indica o seu próprio namespace, prefixo de registo ou chave de assinatura. Estes são-lhe atribuídos, e um manifesto que tentasse declará-los estaria a fazer uma afirmação em que as verificações teriam depois de não acreditar.
O registo assinado contém onze campos: o slug do plugin, a organização proprietária, a organização que o compila, os seus repositórios, o nome da sua chave de assinatura, o seu namespace de implementação, o seu prefixo de registo, o seu esquema de base de dados, os seus domínios, a sua política de alterações e uma lista curta de nomes de imagem antigos que usava antes de o seu prefixo de registo existir. Esta última lista só pode diminuir. Por estar assinada, uma nova assinatura pode remover uma entrada e nada pode acrescentar uma de forma silenciosa. A assinatura é Ed25519 sobre a forma JSON canónica padrão desses onze campos, para que um registo com "Tomás" ou "Sinéad" seja verificado da mesma forma em todo o lado.
Quando uma versão não corresponde ao seu registo, prevalece a primeira recusa:
| Código | Quando | HTTP |
|---|---|---|
DELIVERY_IDENTITY_MISSING |
Não existe registo para o plugin | 403 |
DELIVERY_PATH_REFUSED |
Um envio de imagem fora do prefixo de registo que não consta da lista assinada de nomes antigos | 403 |
NAMESPACE_MISMATCH |
Uma implementação destinada a outro namespace | 403 |
IMAGE_NAME_COLLISION |
Um nome de imagem já reivindicado por outro plugin | 409 |
CHANGE_CLASS_NOT_PERMITTED |
Uma classe de alteração que a política não governa | 403 |
IMAGE_NAME_COLLISION é a que surpreende as pessoas. Escolha outro nome e nunca reutilize um: um nome de imagem partilhado significa que a promoção de um plugin pode mover os pods de outro plugin.
Migrações, confirmadas e com âmbito definido
Uma migração é entregue dentro da imagem do seu plugin e é executada antes de a nova versão arrancar, através do único executor de migrações do SDK, nexus-migrate. Não escreve o seu próprio aplicador. Antes de qualquer versão poder avançar, o mesmo executor aplica as suas migrações um ficheiro de cada vez numa base de dados descartável, para que uma migração que falhe, falhe aí. A compilação shadow do modelo base chama o executor uma vez por ficheiro, por ordem, e regista cada ficheiro tal como a produção fará.
As regras do executor são as que as barreiras verificam, escritas como código:
- Liga-se com a função de migrador do seu esquema e executa cada ficheiro como proprietário do esquema. Qualquer outro início de sessão, a começar por um superutilizador, é recusado. Um ficheiro que tente mudar ele próprio de função é recusado antes de qualquer execução.
- O ficheiro de tenancy, numerado 0, nunca é editado depois de aplicado. Uma alteração à tenancy recebe o seu próprio ficheiro de revisão,
000_tenancy_r<N>.sql, que onexus-tenancy render --revision <N>escreve por si. - Normalmente, o executor detém a transação de cada ficheiro e recusa um
BEGINouCOMMITdentro dela. Um ficheiro que gere as suas próprias transações declara que é executado por instrução, e então cadaBEGINque abre tem de ter correspondência. - Mantém um livro de registo, com uma linha por ficheiro, com o SHA-256 do ficheiro e a forma como foi executado. Um ficheiro aplicado nunca é alterado no local; uma alteração é um novo ficheiro numerado.
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --revision 2 --out migrations/000_tenancy_r2.sqlCom âmbito significa que cada nova tabela tem organization_id, owner_user_id e business_unit_id, mais a coluna marcadora is_demo, a menos que gates/demo-exempt.json isente a tabela com uma justificação, com uma chave primária que começa pela organização e chaves estrangeiras que a transportam, e com segurança ao nível da linha imposta. A barreira migrations-are-scoped verifica essas regras em todos os ficheiros, e migrations-commit-what-they-open confirma que cada ficheiro faz commit do que abre. A segunda barreira existe porque, uma vez, uma migração que fez rollback silenciosamente terminou com 0, e a tabela que devia ter criado nunca existiu.
Há mais um ficheiro que pertence a cada versão. scripts/ci/required-env imprime as variáveis de ambiente de que o seu serviço precisa para arrancar, como uma matriz JSON obtida a partir do seu carregador de configuração. O percurso de lançamento executa-o e recusa uma versão cuja implementação não defina todas elas, para que uma variável em falta seja detetada antes do lançamento, e não por um pod que não arranca.
node scripts/ci/required-envLançar competências
Os dois tipos de skill chegam às pessoas por caminhos diferentes, por isso lance-os de forma diferente.
Uma skill de manifesto, uma linha tipada no skills[] do seu plugin, é entregue com o plugin e passa pela mesma promoção que o resto. A integração sincroniza todo o conjunto de skills com o registo a cada versão. Se deixar uma skill fora do conjunto, esta fica desativada, e na Enterprise uma sincronização com uma skill inválida não aplica nenhuma, pelo que a versão anterior continua em execução em vez de metade da nova.
Uma skill do Skills Engine é publicada a partir da biblioteca. No Enterprise, uma skill que adicione uma ferramenta de escrita aguarda que duas pessoas designadas a aprovem com as suas passkeys, e o proponente não pode ser uma delas. Uma versão aprovada é depois executada em modo sombra, depois em canary para uma unidade, sujeita a critérios designados, e depois para todos, e para automaticamente se um critério não for cumprido. Se o seu plugin e uma skill do Skills Engine dependerem um do outro, publique primeiro a skill e deixe-a chegar a todos antes de a versão do plugin que a invoca sair do piloto.
Canais e instalações
Depois de uma versão ter passado o piloto e chegado a todas as unidades, é disponibilizada num canal, e cada unidade escolhe o seu canal. O respetivo administrador aprova cada mudança. A página Canais e instalações mostra que unidades executam que versão, com as taxas de erro apenas em contagens: vê como a sua extensão se comporta, nunca o que alguém fez com ela.
O nosso plugin carrier-sync executa três versões em simultâneo, e isso é normal. A maioria das unidades está na versão atual, uma unidade mantém-se numa versão mais antiga num canal mantido até uma data indicada, e uma versão candidata está num canal que ainda ninguém escolheu. Não lute contra isso; uma unidade que precisa de estabilidade para uma auditoria tem direito a ela.
Os registos e métricas da sua extensão
A página de registos e métricas do seu pack está limitada às suas próprias cargas de trabalho, nas unidades onde tem permissão para consultar. Pode filtrar por unidade e ambiente, e vê contagens, tempos e estados.
Os campos pessoais são substituídos antes de uma linha ser escrita, e o conteúdo dos clientes, como o texto de reclamações, o correio ou o conteúdo de documentos, nunca é escrito nos registos. Os registos são conservados durante 14 dias. A organização é definida pelo gateway, nunca pela sua consulta, pelo que uma consulta que indique outra organização é recusada com TENANT_BOUNDARY. O assistente na barra lateral pode ler os mesmos registos consigo, e apenas esses: quando lhe perguntei por que razão os registos de excursão chegaram com atraso numa manhã, ele atribuiu 18 minutos de novas tentativas a leituras duplicadas provenientes da alimentação elétrica de um cais.
Reversão
Existem dois tipos de reversão, e ambos são alterações revistas e não interruptores.
A reversão de um ambiente utiliza a versão anterior. Cada ambiente conserva-a durante 30 dias. A reversão é preparada como uma alteração à versão, pré-visualiza o que irá fazer e requer uma segunda pessoa; depois de aprovada, o pipeline reverte em cerca de um minuto. Cada reversão é cronometrada, tal como cada simulacro, por isso pratique uma antes de precisar dela. A reversão de uma unidade utiliza a página Canais e instalações. O modal de reversão indica o que muda (essa unidade volta a executar a versão mais antiga, e a sua taxa de erro é monitorizada durante uma hora), o que se mantém (as outras unidades, bem como as definições e os registos da unidade), o motivo e quem é a segunda pessoa: o administrador dessa unidade.
As definições e os registos são mantidos durante uma reversão, por isso planeie cada versão partindo do princípio de que a versão anterior poderá voltar a ser executada sobre os dados que a mais recente escreveu. Essa é a razão prática para manter as migrações aditivas dentro de uma versão que possa ter de reverter, e a razão pela qual pedimos a duas pessoas que aprovem cada uma delas. Uma alteração ao modelo é igual: um revisor pode, e deve, pedir o plano de reversão de um pedido de alteração ao grafo antes de o aprovar.
As skills revertem de forma mais suave. Mover a etiqueta live de volta para uma versão anterior é um único passo, e as execuções já em curso terminam na versão com que começaram.
Descontinuar uma versão
Uma versão, depois de criada, nunca é editada. Uma versão que já não deve ser utilizada é retirada, e uma correção é lançada com um novo número de versão. Os próprios canais de lançamento do SDK seguem o mesmo hábito: uma versão defeituosa do SDK é retirada, nunca substituída por conteúdo diferente com o mesmo número. Siga este exemplo, porque um número de versão que pode corresponder a duas compilações diferentes torna inútil qualquer evidência sobre ele.
Retirar um plugin ou pack impede novas instalações. As unidades mantêm a versão que executam até mudarem, por isso a retirada é um sinal e um prazo, não um interruptor de desligar. Indique aos administradores das unidades para que versão devem mudar e até quando.
Descontinuar uma skill segue a mesma ideia, com um passo adicional. O Skills Engine move todos os chamadores restantes para uma substituta depois de executar os casos da substituta, impede novas execuções e conserva as versões, os casos e os registos de execução selados, para que a skill possa ser reposta caso a substituta se revele errada.
Uma lista de verificação de lançamento
Esta é a lista que lemos antes de cada versão do Cold chain. É curta porque a plataforma verifica a maior parte por nós.
- As versões coincidem: o manifesto,
pack.jsone o modelo de conhecimento, se tiver mudado. - Todos os critérios estão verdes localmente, a partir de um estado limpo, e cada novo teste foi comprovado a falhar primeiro.
- A página Manifesto e permissões não mostra qualquer alargamento, ou o alargamento é o pretendido e os revisores sabem porquê.
- Cada migração é um novo ficheiro numerado, com âmbito definido, e aplicado sem erros numa base de dados descartável.
scripts/ci/required-envlista todas as variáveis de que o serviço necessita, e a implementação define cada uma delas.- O plano de reversão está escrito na alteração, incluindo para qualquer alteração ao modelo.
- Dois revisores que não sejam o autor estão disponíveis esta semana.
O último item parece trivial. É o que atrasou mais versões nossas do que todos os critérios juntos.



