Formatos de arquivo de changelog: JSON, YAML ou só Markdown
6 min de leitura
A maioria dos times começa um changelog como arquivo Markdown porque é o caminho de menor resistência: legível no diff de um pull request, legível no GitHub sem renderizar nada, e familiar para qualquer um que já escreveu um README. Essa escolha funciona bem até algo além de uma pessoa precisar ler o arquivo, uma página, um widget, um resumo por email, e aí o formato para de ser de graça. Automação de changelog cobre a exigência estrutural em geral, um tipo, uma data, um corpo e um link; isso aqui é sobre qual formato de arquivo realmente entrega essa estrutura e quanto custa chegar lá com cada um.
O que há de errado com um changelog Markdown simples?
Nada, até algo precisar reparseá-lo de volta em campos. Um título, uma data e uma lista com marcadores embaixo é trivial de ler para uma pessoa e genuinamente difícil de parsear de forma confiável, porque Markdown não tem esquema: a data pode estar no título, em negrito na primeira linha, ou totalmente ausente em uma entrada antiga, e cada uma dessas variações é Markdown válido que uma pessoa lê corretamente e um parser não. Times que automatizam um changelog Markdown geralmente acabam escrevendo um parser caseiro baseado em regex que quebra na primeira vez que a formatação de uma entrada desvia mesmo que levemente, o que é frequente, porque nada força consistência na hora de escrever.
O que um formato estruturado realmente traz?
Uma garantia de que toda entrada tem a mesma forma, verificada quando a entrada é escrita em vez de adivinhada quando é lida. Um arquivo JSON ou YAML com um schema definido, tipo, data, versão, público, corpo, link, falha de forma barulhenta se um campo obrigatório está faltando, do mesmo jeito que uma resposta de API estrita faria; um arquivo Markdown simplesmente renderiza o que está lá, correto ou não. Essa diferença é invisível até o dia em que um script precisa da data de cada entrada para ordenar um feed, e metade das entradas tem isso em um lugar diferente.
# CHANGELOG.yml
- date: 2026-09-05
type: breaking
version: v2
audience: api
body: "POST /invoices now rejects a currency mismatch instead of silently converting."
link: /blog/api-changelog/Isso significa que o arquivo legível por humanos precisa sumir?
Não, e tentar fazer um arquivo YAML ou JSON servir dobrado como o que uma pessoa lê em um pull request costuma ser um erro na direção oposta: revisar um diff de JSON aninhado é pior do que revisar uma frase de prosa, e uma revisora que precisa parsear mentalmente uma estrutura de dados para pegar um erro de redação é uma revisora que eventualmente vai parar de pegar erros de redação. Os dois formatos podem coexistir: dados estruturados são a fonte de verdade que uma pipeline de automação lê, e uma renderização Markdown ou HTML gerada é o que uma pessoa realmente revisa e lê, produzida a partir do arquivo estruturado em vez de mantida manualmente ao lado.
| Formato | Legível por humanos como está | Parseável por máquina sem código sob medida | Modo de falha comum |
|---|---|---|---|
| Markdown | Sim | Não | Forma inconsistente de entrada quebra parsers ingênuos |
| JSON | Ruim | Sim | Verboso; fácil de editar à mão para JSON inválido |
| YAML | Razoável | Sim | Sensível a espaço; uma indentação errada é um erro de parse silencioso, não barulhento |
Qual formato estruturado é realmente mais fácil de editar à mão, JSON ou YAML?
YAML, para quem escreve entradas à mão em vez de por um gerador, porque elimina as aspas e o pareamento de chaves que JSON exige para cada string e objeto aninhado. O trade-off é que a sensibilidade do YAML a espaço falha silenciosamente de um jeito que os desencontros de chaves do JSON geralmente não fazem: um parser JSON rejeita de cara uma entrada malformada, enquanto um parser YAML pode aceitar um arquivo mal indentado e simplesmente parseá-lo na estrutura errada, o que é uma falha pior porque nada avisa que isso aconteceu. Se as entradas são sempre escritas só por um script, esse trade-off praticamente desaparece e o parsing mais estrito do JSON se torna a escolha padrão mais segura.
Uma página de changelog precisa do próprio formato estruturado, separado do arquivo que a alimenta?
Não um separado, o mesmo renderizado de forma diferente. Uma página de changelog cobre como tornar a própria página legível por máquina por meio de um feed JSON e marcação schema.org; esse feed é saída gerada, não uma segunda fonte de verdade a ser mantida sincronizada com o arquivo subjacente. Manter dados estruturados à mão em dois lugares, um arquivo fonte e o feed de uma página, é como os dois acabam divergindo, então a decisão de formato de arquivo tomada aqui deveria ser a única coisa da qual tudo a jusante, página, widget, email, é gerado, nunca copiado à mão.
Vale a pena o custo de migração de converter um changelog Markdown existente para um formato estruturado?
Geralmente só quando automação é o objetivo real, não antes. Um projeto de uma pessoa só publicando um arquivo Markdown em um README do GitHub não tem uma necessidade real de automação, e converter para YAML não compra nada além de cerimônia. A conversão se paga sozinha no momento em que mais de um consumidor a jusante, uma página, um email de resumo, um feed público, precisa ler os mesmos dados, porque esse é exatamente o ponto onde as inconsistências de um parser Markdown começam a produzir saída visivelmente errada em vez de só ser chata de manter.
FAQ
Um changelog Markdown pode ser tornado parseável sem trocar de formato completamente? Parcialmente, com frontmatter: um pequeno bloco YAML no topo de cada entrada (data, tipo, versão) ao lado de um corpo Markdown para a prosa. Isso consegue os campos estruturados de que um parser precisa sem forçar a entrada inteira em JSON ou YAML, e é um meio-termo razoável para um time ainda não pronto para uma migração completa.
O formato do arquivo importa para SEO ou para como uma página de changelog rankeia? Não diretamente. Buscadores leem a página renderizada, não o arquivo fonte, então o formato do arquivo é invisível para eles; o que importa para a própria página é se ela é legível por máquina por direito próprio, o que é uma questão separada do que a gera.
Toda entrada de changelog deveria passar pelo mesmo arquivo, ou tipos podem ser divididos entre vários arquivos? Um arquivo só é mais simples até o volume de entradas torná-lo incômodo de diferenciar ou revisar; dividir por ano ou por categoria é uma válvula de escape razoável assim que os diffs de um único arquivo ficam grandes demais para revisar com sensatez, mas isso adiciona um passo de merge antes de qualquer coisa a jusante conseguir ler “todas as entradas” como uma lista só.
Existe um formato padrão de arquivo de changelog, como existe um padrão para RSS? Não um amplamente adotado. Keep a Changelog propõe uma convenção Markdown, e várias ferramentas têm a própria; um changeset é um arquivo Markdown com frontmatter YAML que nomeia o pacote e o bump, que é o padrão de frontmatter descrito acima. Nenhum deles é um formato que outras ferramentas leem de cara do jeito que leitores de RSS entendem RSS universalmente.
As afirmações técnicas deste artigo não foram revisadas de forma independente. Se algo estiver errado, avise a gente e vamos corrigir.