# Changelog pages

## Purpose

A changelog records notable changes to the platform, newest first. It is a **record**, not one of the four Diátaxis forms: it does not teach, instruct, or explain, and a reader consults it to answer one question, which is what changed and when.

## When to use

- Add an entry when a change alters what a reader can do, see, or configure.
- Add it when a default changes, a limit moves, or a feature is removed.

Do not add an entry when:

- Nothing changed for the reader. An internal refactor is not a changelog entry.
- The change needs instructions. Write the [how-to guide](/en/documentation/style-guide/content/how-to-guides/) and link it from the entry.
- The change deserves reasoning. Write the [concept page](/en/documentation/style-guide/content/concept/) and link it.

## Register

Descriptive: 25 words per sentence, active voice, passive only when the actor is unknown. Tone: factual, plain, impersonal. [Sentence structure](/en/documentation/style-guide/writing/sentence-structure/) holds the rules.

## Structure

Each entry is one `DocUpdate`: the date, the version, and the product sit in the left column, and the notes run on the right. An entry covers one product on one date, so a date that ships two products gets two entries. The notes run three to six short paragraphs; a release that lists many changes groups them under kind headings instead.

**Required components**

- **A `DocUpdate` entry**, newest first. `label` is the date, `<Month> <day>, <year>`: dates are allowed in changelogs and only in changelogs. `anchor` is the date as a slug, `july-10-2026`.
- **The opening sentence**: `**<Product>** now <verb>s <what it now does>.`, plus the concrete detail: the flag, the field, or the default.
- **What it means concretely**: what works without configuration now, or what behaves differently.
- **Who is not affected**: existing configurations, earlier versions, accounts that did not opt in.
- **The closing link**: `For more information, refer to [<the documenting page>](/en/documentation/.../).`

**Optional components**

- **The product and the version**: `tags={['<Product>']}` and `description="Version <x.y.z>"`, when the release names a product or a version.
- **Kind headings**: `### Features`, `### Improvements`, `### Bug Fixes` inside the notes, when one entry lists more than one kind of change.
- **Migration or opt-in steps**: with a code sample, when an API, CLI, or configuration changed.

## Template

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

<DocUpdate label="<Month> <day>, <year>" description="Version <x.y.z, when there is one>" tags={['<Product>']} anchor="<month>-<day>-<year>">

**<Product>** now <verb>s <what it now does>, <the concrete detail: the flag, field, or default>.

<What this means in practice: what works without configuration now, or what behaves differently.>

<Who is not affected: existing configurations, earlier versions, accounts that did not opt in — and how they can opt in.>

<When an API, CLI, or configuration changed: the migration or opt-in, with a code sample.>

For more information, refer to [<the documenting page>](/en/documentation/.../).

</DocUpdate>
```

## Rules

- **Open with the product as the subject.** `**<Product>** now <verb>s <what it now does>.` Present tense, never `we`, never `Azion is excited to`.
- **State who is not affected.** A reader's first question about any change is whether it breaks them; answer it before they ask.
- **Show migration or opt-in steps when the surface changed.** An API, CLI, or configuration change gets a code sample; two lines is enough.
- **Close every entry with the documentation link.** An entry that documents the feature in full is a page filed in the wrong place.
- **Give every entry an `anchor`.** The page outline lists one row per date and links the first entry with that date, so `#<date>` keeps resolving. A second entry on the same date takes `<date>-<product>`: `july-10-2026-marketplace`.
- **Leave a blank line after the opening tag and before the closing one.** Without them the notes render as one literal paragraph.
- **Never rewrite an entry.** Correct it with a new dated entry; the log is append-only.
- **Keep the product names of the period.** A dated record keeps the names it was written with; only new entries use current names.
- **End the page with its oldest entry.** A changelog has no closing section: no Next steps and no Related resources.

## Examples

- [Changelog archive](/en/documentation/changelog/previous-year/): one entry per month, from 2016 to 2021.

This trimmed entry shows the date, the product tag, and the entry shape:

```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>
```

## Related

- [Documentation terminology](/en/documentation/style-guide/writing/terminology.md): The historical-name exemption that applies here.
- [Choose a content type](/en/documentation/style-guide/content/choose-a-content-type.md): The full catalogue of page kinds.