Política de Versionamento
Diretrizes de versionamento de metodologias — convenções SemVer para frameworks e aplicações.
Convenções SemVer
Todas as metodologias dMRV no Ecossistema Carrot seguem o Versionamento Semântico (SemVer) para comunicar a natureza e o impacto das mudanças:
| Nível | Significado | Exemplo |
|---|---|---|
| MAJOR | Mudanças incompatíveis na lógica de verificação que podem afetar integrações existentes ou alterar resultados | v1.0.0 → v2.0.0 |
| MINOR | Novas regras adicionadas ou melhorias não incompatíveis em regras existentes | v1.0.0 → v1.1.0 |
| PATCH | Correções de bugs, atualizações de documentação ou correções menores que não alteram o comportamento das regras | v1.0.0 → v1.0.1 |
Versionamento do framework
Os documentos do Methodology Verification Framework (MvF) são versionados independentemente. Cada versão representa um estado específico da especificação de verificação:
- Mudanças MAJOR exigem uma nova versão do framework e podem incluir um guia de migração para Integradores cujos padrões de envio de dados precisam ser adaptados.
- Mudanças MINOR adicionam novos requisitos de verificação sem alterar os existentes.
- Mudanças PATCH esclarecem especificações ambíguas ou corrigem a documentação.
Versionamento da aplicação
As releases do Methodology Verification Application (MvA) acompanham a versão MAJOR do MvF para manter o alinhamento entre especificação e implementação:
- Uma nova versão MAJOR do MvF aciona uma nova versão MAJOR do MvA.
- Novas implementações de regras dentro da mesma versão MAJOR do MvF são releases MINOR do MvA.
- Correções de bugs nos processadores de regras são releases PATCH do MvA.
Ciclo de vida da versão
Cada versão passa por estágios definidos:
- Rascunho — Em desenvolvimento; ainda não disponível para uso em produção.
- Revisão — Em revisão pela Comunidade de Especialistas; pode mudar antes da publicação.
- Publicado — Ativo em produção; documentos MassID são avaliados contra esta versão.
- Descontinuado — Substituído por uma versão mais recente; um período de transição permite que os integradores se adaptem.
Política de transição
Quando uma versão é descontinuada:
- Período de transição — Integradores e participantes da cadeia de suprimentos recebem aviso prévio para se adaptar à nova versão.
- Créditos existentes — Créditos emitidos sob uma versão descontinuada permanecem válidos e negociáveis. A descontinuação não afeta retroativamente reivindicações previamente verificadas.
- Novas submissões — Após o período de transição, novas submissões de MassID devem estar em conformidade com a versão publicada atual.
Princípios de atualização
Todas as atualizações de metodologias são regidas por três princípios invioláveis:
- Preservação da rastreabilidade histórica — Nenhuma atualização pode apagar ou tornar inacessível uma versão anterior. Resultados gerados sob uma versão devem permanecer auditáveis segundo as regras daquela versão. O ecossistema mantém um repositório versionado com histórico completo de mudanças.
- Continuidade operacional — Atualizações não podem causar interrupção abrupta em metodologias ativas. Quando mudanças afetam regras de validação, cálculos ou elegibilidade, um período de transição permite a coexistência.
- Governança transparente — Toda mudança deve ser justificada, documentada e comunicada. A documentação registra: o que mudou, por quê, quem propôs, quem aprovou e quando entra em vigor.
Categorias de alteração
| Categoria | Impacto | Incremento de versão | Aprovação |
|---|---|---|---|
| Correções menores | Sem alteração de lógica/cálculo/elegibilidade. Erros de digitação, formatação, referências, esclarecimentos de redação. | PATCH | Curadoria interna com registro de alteração |
| Atualizações operacionais | Afetam a execução, mas não a base científica. Adição/ajuste de regras, refinamento de elegibilidade, novos eventos, atualizações de metadados. | MINOR | Análise técnica pela curadoria, consulta à Engenharia quando o MvA é impactado |
| Revisões substantivas | Modificam a base de cálculo, parâmetros-chave, lógica de quantificação ou fundamentos. | MAJOR | Ciclo completo de homologação |
Quem pode propor alterações
Mudanças podem ser propostas por: autor original do MvF, equipe de Operações & Metodologias, equipe de Engenharia, VVBs independentes e membros da Comunidade de Especialistas. Cada proposta deve incluir: descrição, justificativa técnica, impacto esperado e categoria proposta.
Coexistência de versões
Quando uma nova versão do MvF é publicada, a anterior não é desativada imediatamente. Ambas coexistem durante um período de transição para MassIDs em trânsito.
A regra governante é a versão de entrada: cada MassID é avaliado sob a versão do MvF ativa no momento de seu primeiro evento (tipicamente a coleta). Novos MassIDs após a data de vigência seguem as regras atualizadas.
Períodos de transição típicos: 30–90 dias para atualizações operacionais, mais longos para revisões substantivas (caso a caso).
Saiba mais sobre o ciclo de vida da metodologia · Saiba mais sobre a política de descontinuação