# 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](/pt-br/documentacao/guia-de-estilo/conteudo/guias-how-to/) e aponte para ele na entrada.
- A mudança merece raciocínio. Escreva a [página de conceito](/pt-br/documentacao/guia-de-estilo/conteudo/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](/pt-br/documentacao/guia-de-estilo/escrita/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

```mdx
import DocUpdate from '@aziontech/webkit/doc-update'

<DocUpdate label="<dia> de <mês> de <ano>" description="Versão <x.y.z, quando existe>" tags={['<Produto>']} anchor="<dia>-de-<mes>-de-<ano>">

**<Produto>** agora <verbo> <o que ele passa a fazer>, <o detalhe concreto: a flag, o campo ou o valor padrão>.

<O que isso 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 — e como aderir.>

<Quando uma API, a CLI ou uma configuração mudou: a migração ou a adesão, com um exemplo de código.>

Para mais informações, consulte [<a página que documenta a mudança>](/pt-br/documentacao/.../).

</DocUpdate>
```

## 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](/pt-br/documentacao/produtos/changelog/anos-anteriores/): 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:

```mdx
<DocUpdate label="July 10, 2026" tags={['Marketplace']} anchor="july-10-2026">

**Bot Manager** now has new versions for both plans: Bot Manager Lite 0.2.0 and Bot Manager 1.3.0 for the standard plan. The standard plan was formerly named Advanced.

The release adds nine new static rules and two new arguments. The `good_fingerprint_list` argument allows listed fingerprints to bypass Bot Manager validation. The `block_ai_bots` argument blocks known AI user agents automatically.

This release does not upgrade existing installations. To get the new Lite version, launch [Bot Manager Lite](https://console.azion.com/marketplace/solution/azion/bot-manager-lite) through Azion Marketplace. The standard version of [Azion Bot Manager](/en/documentation/platform/firewall/#bot-manager) remains available on demand, upon request to the Service Delivery team.

For more information, refer to [Azion Bot Manager Lite](/en/documentation/platform/firewall/bot-manager/bot-manager-lite/).

</DocUpdate>
```

## Relacionados

- [Terminologia da documentação](/pt-br/documentacao/guia-de-estilo/escrita/terminologia.md): A isenção de nomes históricos que vale aqui.
- [Escolher um tipo de conteúdo](/pt-br/documentacao/guia-de-estilo/conteudo/escolher-um-tipo-de-conteudo.md): O catálogo completo de tipos de página.