Changelog Guide

Use the changelog to publish product updates for a workspace. It's separate from docs articles, so release notes stay easy to scan and subscribe to.

Where readers find it

Each workspace has a changelog page:

/docs/{workspace}/changelog

Each entry has its own link on that page, in the form /docs/{workspace}/changelog#e{id}. Published entries also appear in the sidebar when a workspace has at least one entry.

Create an entry

  1. Open Admin > Changelog.
  2. Choose the workspace.
  3. Select New entry.
  4. Add a title and Markdown body.
  5. Add tags.
  6. Keep it as draft until it is ready.
  7. Publish it.

Entries support image uploads and video embeds in the Markdown body.

To publish an entry later, give it a future publish date. The entry stays off the changelog page, search, and the feeds until that time.

Tags

Use tags to make updates scannable:

The REST API, MCP, cowl, and the GitHub Action also take common aliases and save the matching tag. added, feature, and features mean new. changed, improvement, and improvements mean improved. fix, fixes, and bugfix mean fixed. removed and deprecation mean deprecated. So the Added, Changed, Fixed, and Removed sections of a Keep a Changelog file get tags without extra work.

Drafts and published entries

Draft entries are visible in Admin for members with write access. Public readers only see published entries.

Feeds and exports

Each public workspace changelog has machine-readable outputs:

/w/{workspace}/changelog.rss
/w/{workspace}/changelog.md

Use RSS for subscribers and status pages. Use Markdown exports for agents, release summaries, and support workflows.

A workspace export also holds each changelog entry as a Markdown file, with its title, tags, status, and date in front matter.

Agents and automation

Agents read the changelog with the list_changelog tool or the REST API, and can ask for the entries of the last 30 days. To publish release notes from your repository, use the GitHub Action. It turns each version of a Keep a Changelog file into one entry.

Good entry shape

Keep entries short: