Versionamento

O que você pode confiar que não muda por baixo dos seus pés — tanto no vocabulário YAML quanto nos pacotes NuGet que você referencia.

O schema YAML: pipevine.dev/v1

apiVersion: pipevine.dev/v1 está congelado. "Congelado" aqui tem um significado concreto, não uma intenção de marketing: o vocabulário inteiro documentado na referência de configuração YAML — todo campo, todo step, todo recurso — está implementado e coberto por testes. Não existe campo "reservado para o futuro" que pareça funcionar mas não faça nada.

O schema JSON publicado (usado por editores para autocompletar e validar seu YAML) é gerado diretamente a partir do modelo de dados do framework, nunca escrito à mão — o arquivo comitado é sempre exatamente o que o modelo atual produz, verificado automaticamente a cada mudança. Um schema desatualizado, ou uma mudança silenciosa no modelo, é pego antes de chegar a você.

O que "congelado" permite, e o que exige uma versão nova

Mudança	Permitida em v1
Novo campo opcional, novo step, novo provider	Sim — é assim que a extensibilidade por pacotes de terceiro funciona, sem tocar no core
Novo valor de enum que consumidores existentes não precisam reconhecer	Sim
Tornar um campo obrigatório em opcional (relaxar uma exigência)	Sim
Remover ou renomear um campo existente	Não — exige pipevine.dev/v2
Tornar um campo opcional em obrigatório	Não — exige v2
Mudar o tipo de um campo existente, ou o significado de um valor já aceito	Não — exige v2
Mudar o comportamento em runtime de um step existente para a mesma configuração	Não — exige v2

Em outras palavras: você pode confiar que um documento pipevine.dev/v1 que funciona hoje continua funcionando amanhã, exatamente do mesmo jeito — mesmo depois de atualizar os pacotes do framework. Novo vocabulário só aparece de forma aditiva; nada existente muda de significado por baixo do seu YAML.

Se o vocabulário precisar crescer de um jeito incompatível com essa tabela, a rota é um apiVersion: pipevine.dev/v2 explícito e novo no documento — nunca uma mudança silenciosa sob v1 — com os dois aceitos lado a lado durante uma transição, exatamente por isso que apiVersion já é versionado desde o primeiro documento que você escreve.

Os pacotes NuGet: SemVer estrito

A superfície pública de cada pacote Pipevine.* — em especial os pacotes de abstração que um autor de extensão implementa (Pipevine.Abstractions, Pipevine.Data.Abstractions, Pipevine.Caching.Abstractions, e os demais) — segue SemVer estrito:

• Uma quebra de contrato (remover um membro público, mudar uma assinatura, mudar o comportamento documentado de algo já público) só acontece numa versão major.
• Toda adição à superfície pública é rastreada explicitamente — não existe "adição pequena o suficiente para não contar como mudança pública".
• Novos membros em interfaces são adicionados como default interface members sempre que possível, especificamente para que uma implementação de terceiro já existente (o seu IStep, o seu IDataProvider) continue compilando sem alteração quando você atualiza a versão do pacote.

Na prática: fixar Pipevine.* numa faixa de versão minor/patch (por exemplo, 1.*) é seguro contra quebras de compatibilidade binária ou de comportamento; só uma mudança de major exige revisão deliberada da sua parte — e, quando acontecer, o motivo estará documentado nas notas da versão.

Para onde ir daqui

• Referência de configuração YAML — o vocabulário completo, hoje.
• Extensibilidade — como estender o vocabulário sem esperar por uma versão nova do schema.