Versionamento

Toda alteração em uma regra ou em uma análise publicada gera uma nova versão. Cada versão registra quem alterou, quando alterou e o que mudou. Uma versão anterior volta ao ar quando publicada novamente.

A mecânica é a mesma para a regra e para a análise: uma versão publicada é imutável, uma nova versão começa como rascunho, e a publicação substitui o que está no ar. As diferenças da análise estão em Versões de análise.

Status

Cada versão está em um dos seguintes status:

Status	Comportamento
Rascunho	aceita modificação livre e só passa a valer depois de publicada
Em observação	executa em paralelo com a versão ativa, sem decidir nada, conforme Observação
Ativa	está publicada e em uso pela API; não aceita modificação, e uma alteração gera uma nova versão
Inativa	já esteve ativa em algum momento; é mantida para rastreabilidade e volta ao ar pelo botão Publicar
Arquivada	está oculta no painel e preservada no histórico; permanece visível ao inspecionar eventos antigos que a utilizaram

Uma regra ou uma análise admite no máximo uma versão ativa e uma versão em observação ao mesmo tempo. Uma versão publicada apresenta o botão Nova versão a partir desta em lugar do botão de edição, e informa que não pode ser editada.

Nova versão

O botão Nova versão, na página da regra ou da análise, cria um rascunho a partir de uma das duas origens:

Origem	Conteúdo do rascunho
A partir de uma versão	cópia das condições da versão escolhida, ou das células, na análise; a versão ativa vem selecionada
Em branco	nenhuma condição, ou nenhuma célula, na análise

O menu de uma versão publicada oferece o mesmo caminho, com a versão já escolhida, em Nova versão a partir desta. Editar uma versão publicada não cria rascunho: o rascunho nasce sempre de Nova versão ou de Nova versão a partir desta. Criar uma versão exige o perfil Editor ou Administração.

Um rascunho de regra em branco existe sem condições, mas o editor só salva a regra com ao menos uma condição. A publicação exige o mesmo.

Rascunhos abertos

Uma regra admite até três rascunhos abertos ao mesmo tempo. A página da regra apresenta a contagem, como 1 de 3 rascunhos abertos. Com o limite atingido, a criação de rascunhos está indisponível até que um rascunho seja publicado ou descartado. A análise não tem esse limite.

Arquivar e descartar

Descartar exclui um rascunho em definitivo.

Arquivar preserva o histórico e retira do painel uma regra, uma análise ou uma versão inativa de regra:

Item	Efeito	Restrição
Regra	os rascunhos são excluídos e as versões inativas passam a Arquivada; uma regra que só teve rascunhos é excluída	recusado enquanto alguma versão estiver ativa ou em observação
Análise	a análise e todas as suas versões são arquivadas	recusado enquanto uma regra publicada usar a análise
Versão inativa de regra	a versão passa a Arquivada	a versão ativa e a versão em observação não são arquivadas

O painel não restaura um item arquivado.

Comparação e publicação

Toda versão que pode entrar em vigor (rascunho, inativa ou em observação) apresenta o botão Publicar. Com outra versão ativa, a publicação exige a revisão prévia das mudanças em relação a ela: a tela de comparação abre posicionada entre a versão ativa e a versão a publicar, e o botão de publicar fica no próprio comparativo. Sem versão ativa, a publicação solicita apenas uma confirmação. O painel sinaliza uma regra sem versão publicada, que só passa a valer após a primeira publicação.

A comparação abrange as condições e as ações. Cada linha corresponde a uma condição. As linhas coloridas indicam as condições que mudaram, e uma etiqueta identifica a alteração (adicionada, removida, reordenada ou alterada). Na coluna de ações, uma ação riscada deixa de valer e a que a substitui aparece após a seta; uma ação marcada com + é nova. O comparativo expõe o efeito exato da publicação antes de a versão entrar em vigor.

Na análise, cada linha corresponde a uma célula, com o valor anterior e o novo de cada configuração alterada.

Condições atendidas

Cada condição de uma versão de regra registra quantas vezes foi atendida a cada dia. O painel apresenta a contagem na própria condição, junto com o total de execuções do período. A leitura distingue três situações: o dia em que a regra não recebeu tráfego, o dia em que a regra executou sem que a condição fosse atendida, e o dia em que a condição foi atendida ao menos uma vez.

A contagem localiza a condição que nunca é atendida, seja porque a expressão não corresponde ao tráfego real, seja porque uma condição anterior já preencheu o campo que ela testa. Uma condição que não é atendida nenhuma vez desde a publicação é candidata a revisão antes da próxima versão.

A contagem começa na publicação da versão e considera apenas eventos reais: as simulações ficam de fora. Uma versão recém-publicada, portanto, começa sem leitura.

Observação

Publique uma versão em observação (shadow) antes de ela entrar em vigor. A versão em observação executa em paralelo com a versão ativa, sobre os mesmos eventos reais, e nada do que ela produz altera o resultado do evento: a decisão continua sendo a da versão ativa. O ciclo de vida passa a ser rascunho, observação e ativa.

Uma versão inativa também pode ser colocada em observação. Isso avalia uma versão já substituída sem devolvê-la ao comando das decisões. A versão ativa é a única que não pode ser observada, por já estar decidindo.

Uma versão em observação é imutável, como a ativa: editá-la cria um novo rascunho. A versão promovida é exatamente a que foi observada, sem reescrita das ações.

Saídas observadas

A observação é seletiva. Ao publicar, você marca quais saídas quer acompanhar. A plataforma grava cada saída marcada no mesmo evento, em um campo com o sufixo _shadow, ao lado do valor que a versão ativa gravou. O campo _shadow acompanha as configurações de armazenamento do campo de origem (limite de tamanho, truncamento, sensibilidade e casas decimais). Uma alteração no campo de origem que o par observado não comporta é recusada. As saídas não marcadas são descartadas junto com o restante da execução.

Como os dois valores ficam no mesmo evento, a comparação usa as telas existentes: filtros em Explorar, métricas e dashboards comparam o campo e o seu par observado sem configuração adicional.

Altere as saídas observadas a qualquer momento, sem republicar a versão. Uma versão que não preenche nenhum campo não tem saídas para observar e não pode ser publicada em observação.

Todo evento processado registra também a versão em observação que o processou, além do nome e da versão da regra ativa. Sem esse registro, um valor observado não poderia ser atribuído à versão que o escreveu, já que cada revisão é uma versão nova.

O que a observação não executa

Uma versão em observação não altera o estado compartilhado que outras execuções leem:

• As ações que gravam em listas são suprimidas. As condições que consultam listas continuam lendo a lista real. Uma regra cujo comportamento é alimentar uma lista e depois consultá-la é observada de forma aproximada, não exata.
• As análises registradas pela versão em observação ficam em janelas próprias, separadas das que a versão ativa alimenta e consulta.

As janelas da observação começam vazias e precisam de uma retenção inteira de tráfego para significar alguma coisa. Ao promover a versão para ativa, as janelas recomeçam do zero pelo mesmo motivo.

Em um tipo de evento com versão em observação, o evento fica visível nas consultas alguns instantes depois do recebimento, e não imediatamente. A gravação espera a execução observada para levar os dois valores no mesmo registro.

Versões de análise

Uma análise segue o mesmo ciclo da regra, com três particularidades.

Toda alteração em uma análise, seja uma célula, seja a ordem da cascata, é feita em um rascunho, e a publicação leva o conjunto inteiro ao ar de uma vez. Não há publicação de uma célula isolada: a cascata é publicada como um todo, e as células nunca estão em versões diferentes entre si.

Uma análise admite vários rascunhos ao mesmo tempo, cada um partindo da versão que o originou. A página da análise apresenta os rascunhos abertos e o caminho para cada um.

Alterar o que uma célula mede, ou a janela em que ela acumula, descarta o histórico já acumulado por essa célula. A célula recomeça vazia e precisa de uma retenção inteira de tráfego para voltar a significar alguma coisa. A comparação assinala essa consequência antes da publicação, e a confirmação é solicitada no momento da alteração. As demais células da análise mantêm as suas janelas.

Histórico

Cada regra e cada análise tem um histórico com as ações realizadas sobre as suas versões: criação, edição, publicação, publicação em observação, retirada de observação, substituição, despublicação, descarte e arquivamento. Cada entrada registra a versão, o autor e o momento.

O histórico exibe as ações mais recentes e mantém as demais recolhidas. A lista de versões é o registro completo.

Rastreabilidade nos eventos

Todo evento processado por uma regra registra o nome da regra e o número da versão que o processou, além da versão em observação, quando houver uma. Esse registro reconstrói depois qual lógica gerou cada valor, inclusive quando a versão já foi substituída ou arquivada.

A ação executar análise publica a versão da análise que decidiu um evento na chave version, que um preencher campo grava no evento.