> ## Documentation Index
> Fetch the complete documentation index at: https://onset.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Writing Releases

> Use the editor, Markdown, images, and media embeds to write clear updates.

## The editor

The release body uses a rich text editor. Use the toolbar, or type Markdown and it converts as you go:

| You type | You get |
| - | - |
| `# Heading` | Heading |
| `**bold**` | **bold** |
| `_italic_` | *italic* |
| `` `code` `` | inline code |
| ` ```lang ` | code block with syntax highlighting |
| `- item` | bulleted list |
| `1. item` | numbered list |
| `> quote` | blockquote |
| `---` | divider |

Pasting Markdown from another tool works too. It converts on paste.

## Images

Drag an image into the editor, paste it from your clipboard, or use the toolbar to upload one.

## Media embeds

Paste a link on its own line and Onset embeds the player:

* YouTube
* Loom
* Vimeo

> [!TIP]
>
> A short Loom walking through a feature usually outperforms three paragraphs describing it.

## Change lists

For releases with many small changes, use the **change list** instead of stuffing everything into the body.

Each entry is a **change type** plus its content. There's no separate title field. You pick the type from a dropdown and write the change itself in the editor, with the same formatting available as the main body. Entries can be reordered by dragging.

A good pattern: the body explains *why this release matters*, the change list covers *everything that changed*.

### Change types

Onset ships with a default set, following the [Keep a Changelog](https://keepachangelog.com) convention:

| Type | Use for |
| - | - |
| **New** | Functionality that didn't exist before. |
| **Changed** | Existing behavior that works differently now. |
| **Deprecated** | Still works, but scheduled for removal. |
| **Fixed** | Bug fixes. |
| **Removed** | Functionality that's gone. |
| **Security** | Vulnerability fixes and security-relevant changes. |

### Customize the types

The list isn't fixed. Go to **Settings → Workspace → Releases** to add your own types, rename existing ones, change their color, or reorder them. Each type has a title and a color, and the order you set is the order shown in the editor dropdown.

> [!TIP]
>
> Marking a change as **Deprecated** or **Removed** is the cheapest migration warning you can give customers, far cheaper than the support thread that follows a silent removal.

## Writing tips

* Lead with what the customer can now do, not what you built.
* Link to the relevant docs page rather than re-explaining it.
* Publish one release per meaningful change rather than a weekly dump. Your feeds and notifications get more useful that way.
* If you're stuck on the first draft, the [AI assistant](https://onset.io/docs/guides/releases/ai-assistant.md) can generate one from your GitHub, Linear, or Jira activity.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.