Changelog & Release Notes Template

​

Overview

1. Individual release note pages — Detailed pages in release-notes/v3.0/ with full content
2. Unified changelog — release-notes/changelog.mdx using Mintlify Update components with tag filters and RSS feed

​

Part 1: Individual Release Note Page

​

Frontmatter

---
title: "Update Title"
date: "YYYY-MM-DD"
severity: "patch"                    # major | minor | patch | hotfix
audience: "All"                      # All | Producers | Developers
tags: ["feature", "improvement"]     # From taxonomy
components: ["dashboard", "billing"] # Affected areas
---

​

File Naming & Placement

release-notes/v3.0/{version}.mdx

Examples:
release-notes/v3.0/3.0.8-26.mdx
release-notes/v3.0/3.0.9.mdx

​

Content Structure

• template-feature.mdx — New features
• template-security.mdx — Security updates
• template-hotfix.mdx — Critical fixes
• template-major-release.mdx — Version launches

​

Part 2: Changelog Update Entry

​

Update Component Template

<Update label="{Month Day, Year}" description="v{version}" tags={["{Tag1}", "{Tag2}"]}>
  ## {Title}

  {1-2 sentence summary of the release.}

  - **{Key change 1}** — Brief description
  - **{Key change 2}** — Brief description
  - **{Key change 3}** — Brief description

  [Read full release notes →](/release-notes/v3.0/{version})
</Update>

​

Placement Rules

• Add new entries at the TOP of changelog.mdx (newest first)
• Place directly after the frontmatter, before all existing Update entries

​

Tag Values (for tag filters)

​

RSS Feed Considerations

<Update
  label="March 1, 2026"
  description="v3.1.0"
  tags={["Platform", "Feature"]}
  rss={{
    title: "v3.1.0 — Major Platform Update",
    description: "Complete redesign of the dashboard with new analytics features."
  }}
>
  ## Major Platform Update

  <Frame>
    <img src="/images/dashboard.png" alt="New dashboard" />
  </Frame>

  [Read full release notes →](/release-notes/v3.0/3.1.0)
</Update>

​

Example: Complete Workflow

​

Step 1: Create the individual page

​

Step 2: Add the changelog entry

<Update label="March 1, 2026" description="v3.0.8-26" tags={["Feature", "Producer"]}>
  ## New Beat Request Analytics

  Producers can now view detailed analytics for their beat request submissions.

  - **Submission tracking** — See which requests you've responded to
  - **Acceptance rate** — Track your success rate over time
  - **Response time metrics** — Monitor your average response speed

  [Read full release notes →](/release-notes/v3.0/3.0.8-26)
</Update>

​

Step 3: Update docs.json navigation

{
  "group": "March 2026",
  "pages": [
    "release-notes/v3.0/3.0.8-26"
  ]
}

​

Reusable Snippets in Release Notes

​

Available Snippets for Release Notes

​

Example Usage

---
title: "Update Title"
date: "YYYY-MM-DD"
severity: "patch"
---

import ReleaseFeedback from "/snippets/sections/release-feedback.mdx";

# Update Title

[... release content ...]

<ReleaseFeedback />

​

Rules

• Every release note should end with <ReleaseFeedback /> instead of a custom Questions/Feedback section
• Security releases should also include <SecurityTrust /> after the feedback section
• Never hardcode contact@beatpass.ca in release notes — use the snippet instead
• Import other snippets (PlatformFee, SupportContact) as needed based on content

​

Writing Guidelines

​

Tone

• Clear and direct
• User-focused (benefits, not technical details)
• Professional but approachable

​

Length

• Individual page: Full detail, 200-600 words
• Changelog entry: Concise summary, 50-100 words + 3-5 bullet points + link to full page

​

Changelog Entry Rules

• Start with a ## Heading inside the Update (creates RSS entry title)
• 1-2 sentence summary paragraph
• 3-5 bullet points with bold lead — description format
• Always end with [Read full release notes →](/release-notes/v3.0/{version})
• No technical jargon — same user-focused language as help docs

​

Review Checklist

• Individual release note page created with correct frontmatter
• Changelog Update entry added at top of changelog.mdx
• Update label uses "Month Day, Year" date format
• Update description uses "v{version}" format
• Update tags use Title Case from approved set (1-3 tags)
• Summary is clear and concise
• Bullet points use **Bold** — description format
• Link to full release notes page included
• docs.json navigation updated with new page in correct month group
• RSS rss prop added if entry contains components/HTML
• <ReleaseFeedback /> snippet used as page footer (not inline contact info)
• <SecurityTrust /> snippet used for security releases
• No hardcoded contact@beatpass.ca — use snippets instead
• Other applicable snippets imported (PlatformFee, SupportContact, etc.)
• No sensitive information exposed
• All changed features are documented