O changelog que a superfície escreve

Abi.changelog separa quebra de acréscimo, com a dica de migração de cada uma — o esqueleto, e não a nota inteira.

Todo release precisa de uma seção no CHANGELOG, e a parte que mais se esquece é justamente a que mais importa: o que quebrou. Abi.changelog escreve o esqueleto a partir da comparação — cada quebra com a dica do que fazer, cada acréscimo — e deixa para você o porquê.

adopt Arcane.Abi as Abi
adopt Arcane.IO as IO
adopt Arcane.OS as OS

pasta := $"{OS.temp_dir()}/df-abi-{randint(100000, 999999)}"
IO.mkdir(pasta)
antes := $"{pasta}/v1.df"
IO.write(antes, "action somar(a, b):\n    yield a + b\naction dobro(x):\n    yield x * 2\nrelay somar, dobro\n")

depois := $"{pasta}/v2.df"
IO.write(depois, "action somar(a, b, c := 0):\n    yield a + b + c\naction triplo(x):\n    yield x * 3\nrelay somar, triplo\n")

texto := Abi.changelog(antes, depois, "2.0.0")
out texto
assert texto.starts_with("## 2.0.0")
assert texto.contains("### Quebra compatibilidade")
assert texto.contains("`dobro`")                 // o que sumiu
assert texto.contains("### Adicionado")
IO.remove_tree(pasta)

• Quebra primeiro. É o que quem atualiza precisa ler antes de qualquer outra coisa.
• Com a dica. "dobro foi removida" não diz o que fazer; a dica diz ("mantenha o nome como casca que chama o novo, ou suba a versão maior").
• O porquê é seu. A ferramenta sabe o que mudou na superfície; por que mudou — e o que isso resolve — só quem escreveu sabe.