Páginas de changelog

Propósito

Um changelog registra mudanças notáveis na plataforma, das mais novas para as mais antigas. Ele é um registro, não uma das quatro formas do Diátaxis: não ensina, não instrui e não explica. O leitor o consulta para responder uma pergunta, que é o que mudou e quando.

Quando usar

• Adicione uma entrada quando uma mudança altera o que o leitor pode fazer, ver ou configurar.
• Adicione quando um valor padrão muda, um limite se move ou uma funcionalidade é removida.

Não adicione uma entrada quando:

• Nada mudou para o leitor. Uma refatoração interna não é entrada de changelog.
• A mudança precisa de instruções. Escreva o guia how-to e aponte para ele na entrada.
• A mudança merece raciocínio. Escreva a página de conceito e aponte para ela.

Registro

Descritivo: 25 palavras por frase, voz ativa, passiva apenas quando o agente é desconhecido. Tom: factual, claro, impessoal. Estrutura de frases tem as regras.

Estrutura

Cada entrada é um DocUpdate: a data, a versão e o produto ficam na coluna da esquerda, e as notas correm à direita. Uma entrada cobre um produto em uma data, então uma data que entrega dois produtos tem duas entradas. As notas têm de três a seis parágrafos curtos; uma release que lista muitas mudanças as agrupa sob headings de tipo.

Componentes obrigatórios

• Uma entrada DocUpdate, das mais novas para as mais antigas. label é a data, <dia> de <mês> de <ano>: datas são permitidas em changelogs e apenas em changelogs. anchor é a data como slug, 10-de-julho-de-2026.
• A frase de abertura: **<Produto>** agora <verbo> <o que ele passa a fazer>., com o detalhe concreto: a flag, o campo ou o valor padrão.
• O que significa na prática: o que funciona sem configuração agora, ou o que se comporta de outra forma.
• Quem não é afetado: configurações existentes, versões anteriores, contas que não aderiram.
• O link de fechamento: Para mais informações, consulte [<a página que documenta a mudança>](/pt-br/documentacao/.../).

Componentes opcionais

• O produto e a versão: tags={['<Produto>']} e description="Versão <x.y.z>", quando a release nomeia um produto ou uma versão.
• Headings de tipo: ### Funcionalidades, ### Melhorias, ### Correções de bugs dentro das notas, quando uma entrada lista mais de um tipo de mudança.
• Passos de migração ou adesão: com um exemplo de código, quando uma API, a CLI ou uma configuração mudou.

Template

Regras

• Abra com o produto como sujeito. **<Produto>** agora <verbo> <o que ele passa a fazer>. Tempo presente, nunca nós, nunca a Azion tem o prazer de.
• Diga quem não é afetado. A primeira pergunta do leitor sobre qualquer mudança é se ela o quebra; responda antes que ele pergunte.
• Mostre a migração ou a adesão quando a superfície mudou. Uma mudança de API, CLI ou configuração recebe um exemplo de código; duas linhas bastam.
• Feche cada entrada com o link da documentação. Uma entrada que documenta a funcionalidade por completo é uma página arquivada no lugar errado.
• Dê um anchor a toda entrada. O sumário da página lista uma linha por data e aponta para a primeira entrada daquela data, então #<data> continua resolvendo. Uma segunda entrada na mesma data recebe <data>-<produto>: 10-de-julho-de-2026-marketplace.
• Deixe uma linha em branco depois da tag de abertura e antes da de fechamento. Sem elas, as notas renderizam como um único parágrafo literal.
• Nunca reescreva uma entrada. Corrija com uma nova entrada datada; o log é somente por acréscimo.
• Mantenha os nomes de produto da época. Um registro datado mantém os nomes com que foi escrito; apenas entradas novas usam os nomes atuais.
• Termine a página na entrada mais antiga. Um changelog não tem seção de fechamento: sem Próximos passos e sem Recursos relacionados.

Exemplos

• Arquivo do changelog: uma entrada por mês, de 2016 a 2021. Ainda sem versão em português.

Esta entrada, de um changelog em inglês, mostra a data, a tag de produto e a forma da entrada:

Relacionados