Superfície e alvos

O que quebra, e qual versão subir

Onze regras nomeadas, o veredito de semver que a mudança exige, e o terceiro balde para o que a superfície não decide sozinha.

O gerenciador de pacotes já tinha semver, forge.lock e verificação de integridade. O que faltava era o que decide o número: nada conferia se a versão nova quebra a anterior, e o bump era escolhido a olho.

bash

dataforge abi v1/lib.df v2/lib.df        # sai com 2 se quebrou
dataforge abi a.df b.df --json           # para o CI ler
dataforge abi a.df b.df --estrito        # o indecidivel conta como quebra

As regras que quebram#

Regra	Por que quebra
`simbolo-removido`	um nome que o módulo exportava deixou de existir; quem o adotava para de compilar no dia da atualização
`especie-trocada`	o nome continua e virou outra coisa (uma ação virou `record`): toda forma de uso muda junto
`aridade-incompativel`	uma chamada que era válida deixou de ser — mais argumento exigido, ou menos aceito
`parametro-renomeado`	a chamada com nome existe aqui (`somar(a := 1, b := 2)`), então o nome do parâmetro é contrato e não só a posição
`tipo-de-parametro`	quem passava o tipo antigo passa a ser recusado pelo `check`
`retorno-trocado`	o tipo de retorno atravessa a fronteira do `adopt`: quem usava o valor perde a conferência, ou é acusado
`campo-removido`	todo acesso ao campo passa a ser erro

As que não quebram#

Regra	Por que é compatível
`simbolo-novo`	ninguém depende dele ainda
`parametro-opcional-novo`	quem chamava com os antigos continua chamando igual
`campo-novo-opcional`	num blueprint, a construção antiga continua valendo

E o terceiro balde#

Há um caso que a superfície não consegue decidir, e fingir que decide seria pior que não ter a ferramenta.

text

  1 ponto(s) que a superficie NAO decide sozinha:
   ? Ponto  [campo-novo-em-record]
      um campo foi acrescentado a um record. Quebra SE ele nao tiver
      valor padrao — e a superficie nao carrega padroes, entao esta e
      uma decisao que so quem escreveu pode tomar
      → se o campo tem valor padrão, é compatível; se não tem, dê um
        — ou suba a versão maior

O veredito#

Veredito	Quando	Saída do comando
`maior`	alguma coisa quebrou	2 — reprova no CI
`menor`	só acréscimos compatíveis	0
`correcao`	a superfície não mudou	0
`desconhecido`	um dos lados não compila	1, com o motivo

No CI#

Conferir contra o commit anterior

# no seu pipeline, antes de publicar
git show HEAD~1:src/main.df > /tmp/antes.df
dataforge abi /tmp/antes.df src/main.df || exit 1

Cada quebra vem com o que fazer ao lado — e quase sempre há um caminho que evita o bump: dar valor padrão ao parâmetro novo, manter o nome antigo como casca que chama o novo, aceitar os dois tipos por um ciclo.