Skip to main content

​
Release Notes Template

Release notes are heartbeat updates. They tell readers what shipped, what needs attention, and where to go for the deep dive—fast.

​
❌ DO NOT COPY — Guidance & Constraints

  • Frontmatter must include title, description, icon, releaseDate, and version. Add tags if you need filters (e.g., ["platform", "oss"]).
  • Lead with a one-sentence headline plus a quick stats table (New features, Fixes, Required action). Keep the TL;DR in an <Info> block; use <Warning> only for breaking changes or deadlines.
  • Organize the body into Highlights, Improvements & fixes (grouped by product), and Known issues. Each bullet links to docs where appropriate.
  • When reshaping older release notes, retain the shipped items and shout-outs—map them to these sections instead of rewriting history.
  • Include an Upgrade checklist with concrete next steps. Optional “Community shout-outs” should remain short.
  • Two-card CTA at the end, as always: left = deeper reference, right = applied next step.

​
✅ COPY THIS — Content Skeleton

Paste the snippet below, swap placeholders, and trim optional sections only once you know they’re unnecessary. 
---
title: [Release title]
description: [1 sentence summary of the release]
icon: "sparkles"
releaseDate: "[YYYY-MM-DD]"
version: "[X.Y]"
tags: ["platform", "oss"] # Optional filters
---

# [Release at a glance]

[Hero sentence that states the biggest win.]

| New features | Fixes | Required action |
| --- | --- | --- |
| [#] | [#] | [Required/Optional + short note] |

<Info>
  **TL;DR**
  - [Highlight #1]
  - [Highlight #2]
  - [Highlight #3]
</Info>

<Warning>
  [Breaking change or deadline reminder. Remove if not needed.]
</Warning>

## Highlights

- **[Feature name]** — [One-sentence benefit]. [Link to doc]
- **[Feature name]** — [One-sentence benefit]. [Link to doc]
- **[Feature name]** — [One-sentence benefit]. [Link to doc]

## Improvements & fixes

**Platform**
- [Improvement sentence with link if relevant.]
- [Fix sentence.]

**Open Source**
- [Improvement sentence.]

**SDKs**
- Python: `[Change summary]`.
- TypeScript: `[Change summary]`.

<Tip>
  [Optional activation hint, e.g., “Enable the feature in Settings → Labs.”]
</Tip>

## Known issues

- **[Issue name]** — `[Status]`. `[Workaround or link].`
- **[Issue name]** — `[Status]`. `[Workaround or link].`

## Upgrade checklist

- [ ] `[Step 1 — update package or config]`
- [ ] `[Step 2 — run migration or toggle setting]`
- [ ] `[Step 3 — verify workflow or metric]`

## Community shout-outs

- [Contributor or team] — `[Short thank-you message].`

{/* DEBUG: verify CTA targets */}

<CardGroup cols={2}>
  <Card
    title="[Deep dive reference]"
    description="[Why readers should open it]"
    icon="book-open"
    href="/[reference-link]"
  />
  <Card
    title="[Apply it next]"
    description="[Set expectation for the follow-up guide or cookbook]"
    icon="rocket"
    href="/[next-link]"
  />
</CardGroup>

​
✅ Publish Checklist

  • Headline sentence and stats table reflect the release accurately.
  • Every highlight, improvement, and issue links to supporting docs when available.
  • <Warning> only appears when a deadline or breaking change exists.
  • Upgrade checklist lists concrete steps (not vague reminders).
  • Exactly two CTA cards at the end with valid links.

​
Browse Other Templates

Quickstart

Operation Guide

Feature Guide

Concept Guide

Integration Guide

Cookbook

API Reference

Parameters Reference

Migration Guide

Release Notes

Troubleshooting Playbook

Section Overview

Contribution Hub

Docs Home