# Release notes

Write one Markdown file per release and get a changelog page, a page per release and the portal releases table.

A section of kind `changelog` reads `changelog/<locale>/` in the project folder, one Markdown file per release.

```json title="project.json"
{
  "nav": {
    "sections": [
      { "id": "guides", "label": "Guides", "kind": "guides" },
      { "id": "changelog", "label": "Changelog", "kind": "changelog" }
    ]
  }
}
```

```md title="changelog/en/2.4.0.md"
---
version: 2.4.0
date: 2026-10-02
title: Scheduled jobs and webhook retries
status: features
---

- Jobs can run on a cron schedule. See [scheduled jobs](../../docs/2.4/en/guides/scheduled-jobs.md).
- Webhook deliveries are retried with backoff.
```

| Field | Required | Value |
|---|---|---|
| `version` | yes | Release version. Also the URL slug: `/<project>/changelog/2.4.0/`. |
| `date` | yes | `YYYY-MM-DD`. Releases are sorted by date, newest first. |
| `title` | yes | One line on what changed. |
| `status` | no | `features` (default), `stable`, `breaking`, `beta` or `deprecated`. Sets the badge. |

The section shows a list of every release and one page per release. The portal home lists the five latest releases
of all projects, unless `home.showReleases` is `false` in `site.json`.

Write links to Markdown files and images relative to the release file, as in the example above. A link to a docs page
opens that page in the current version: here `/<project>/guides/scheduled-jobs/`.

A release missing in a locale is shown from the fallback locale.
