# Versionamento Toda alteração em uma [regra](/pt/rules/) ou em uma [análise](/pt/rules/analyses/) publicada gera uma nova **versão**. O versionamento garante rastreabilidade, registrando quem alterou, quando e o que mudou, e permite reverter para versões anteriores quando necessário. A mecânica é a mesma nos dois casos: uma versão publicada é imutável, a edição parte dela para um rascunho, e a publicação substitui o que está no ar. O que difere na análise está em [Versões de análise](#versões-de-análise). ## Status Cada versão pode estar em um dos seguintes status: - **Rascunho**: pode ser modificada livremente. Só passa a valer depois de publicada. - **Em observação**: publicada em paralelo com a versão ativa, sem decidir nada. Descrita em [Observação](#observação). - **Ativa**: versão publicada, em uso pela API. Não pode ser modificada: alterações geram uma nova versão. - **Inativa**: já esteve ativa em algum momento. Mantida para rastreabilidade e pode ser reativada a qualquer momento. - **Removida**: oculta no painel, mas 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. ## Comparação e publicação A publicação de uma versão exige a revisão prévia das mudanças em relação à versão ativa. 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, após a revisão. Uma regra sem versão publicada é sinalizada como tal e 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 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, apresentado 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 executou sem que a condição fosse atendida, e o dia em que ela 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 Uma versão pode ser publicada **em observação** (*shadow*) antes de entrar em vigor. Nesse estado ela é executada em paralelo com a versão ativa, sobre os mesmos eventos reais, e nada do que 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, o que permite avaliar 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. Cada saída marcada é gravada no mesmo evento, em um campo com o sufixo `_shadow`, ao lado do valor que a versão ativa gravou. 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](/pt/admin/explore/), [métricas](/pt/behavioral/metrics/) e dashboards comparam o campo e o seu par observado sem configuração adicional. As saídas observadas podem ser alteradas 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 não seria possível atribuir um valor observado à 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](/pt/rules/lists/) são suprimidas. As condições que consultam listas continuam lendo a lista real, de modo que uma regra cujo comportamento é alimentar uma lista e depois consultá-la é observada de forma aproximada, não exata. - As [análises](/pt/rules/analyses/) 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, porque a gravação espera a execução observada para levar os dois valores no mesmo registro. ## Versões de análise Uma [análise](/pt/rules/analyses/) segue o mesmo ciclo da regra, com três particularidades. Toda edição em uma análise publicada, seja uma célula, seja a ordem da cascata, cria 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, de modo que as células nunca ficam 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, que 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 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. Isso permite reconstruir depois qual lógica gerou cada valor, inclusive quando a versão já foi substituída ou removida. A versão da análise que decidiu um evento é registrada pela ação [executar análise](/pt/rules/actions/run_analysis/), no destino **Versão**.