Changelog

The changelog displays product updates, new features, bug fixes, and breaking changes in a chronological feed. Users access it at /changelog, and entries are stored in apps/web/content/changelog/.

A well-maintained changelog builds trust, reduces support tickets about "what's new," and demonstrates active product development to potential customers.

The changelog is a reverse-chronological feed of product updates, organized by date and optionally by version, that communicates what changed and why it matters to users.

• Use the changelog when: announcing releases, bug fixes, new features, deprecations, or breaking changes that affect users.
• Use the blog when: writing in-depth tutorials, thought leadership, or content that requires context beyond "what's new."
• Use documentation when: the change requires users to learn new workflows or reference new features.

If unsure: if it fits in one screen and answers "what changed?", use changelog. If it needs explanation beyond that, write a blog post and link from the changelog entry.

Changelog Structure

Entries are stored in apps/web/content/changelog/:

apps/web/content/changelog/
├── 2025-01-15-custom-roles.mdoc
├── 2025-01-10-performance-improvements.mdoc
├── 2025-01-05-bug-fixes.mdoc
└── 2024-12-20-v2-launch.mdoc

Naming Convention

Use descriptive, SEO-friendly slugs that include the date:

YYYY-MM-DD-descriptive-slug.mdoc

Examples:

• 2025-01-15-custom-roles-and-permissions.mdoc
• 2025-01-10-50-percent-faster-api.mdoc
• 2025-01-05-stripe-integration-fix.mdoc

Entry Frontmatter

---
publishedAt: "2025-01-15"
title: "Custom Roles & Permissions"
description: "Create custom roles with granular permissions for team members."
categories: []
tags: []
status: "published"
---

Entry Structure

Follow a consistent structure for each entry:

---
publishedAt: "2025-01-15"
title: "Custom Roles & Permissions"
description: "Create custom roles with granular permissions for team members."
status: "published"
---
## What's New
### Custom Roles
You can now create custom roles with granular permissions:
- Define custom role names beyond Owner, Admin, Member
- Assign specific permissions to each role
- Control access at the feature level
### Improved Team Dashboard
The team dashboard now shows role assignments and permission summaries.
## Bug Fixes
- Fixed email verification timeout on slow connections
- Resolved session persistence issue after password reset
- Corrected timezone display in activity logs
## Breaking Changes
- `getTeamRole()` now returns a `Role` object instead of a string
- Minimum Node.js version increased to 20.x

Categorizing Updates

Use consistent categories to help users scan:

Versioning Strategy

For products with formal releases, include version numbers:

title: "v2.5.0 - Custom Roles & Permissions"

For continuous deployment, use date-based entries without version numbers.

Semantic Versioning Reference

If using versions:

• Major (3.0.0): Breaking changes, major rewrites
• Minor (2.5.0): New features, backward compatible
• Patch (2.4.1): Bug fixes, no new features

Writing Effective Entries

1. Lead with the benefit: "You can now..." not "We added..."
2. Be specific: "50% faster API response" not "Performance improvements"
3. Link to documentation: If a feature needs explanation, link to docs
4. Acknowledge breaking changes: Explain what changed and how to migrate
5. Credit contributors: For open source or community contributions

Good Example

## What's New
### Real-time Notifications
You can now receive instant notifications when team members join, leave, or 
update their roles. Notifications appear in the dashboard header and can be 
configured per-user in [notification settings](/docs/notifications).
- Browser push notifications (requires permission)
- In-app notification center with read/unread status
- Email digest option for offline users

Weak Example

## Updates
- Added notifications
- Fixed some bugs
- Made things faster

Common Pitfalls

• Bundling too many changes: One major feature per entry. Multiple small fixes can be bundled.
• Missing dates: Every entry needs publishedAt. Undated entries confuse users about recency.
• Vague descriptions: "Bug fixes" tells users nothing. Specify what was fixed.
• Forgetting breaking changes: Always call out breaking changes prominently with migration steps.
• Inconsistent formatting: Use the same structure (What's New, Bug Fixes, etc.) across all entries.
• No links to documentation: New features should link to their documentation for details.
• Giant entries: Break major releases into multiple focused entries or create a blog post with summary.

Related Documentation

• Blog System - In-depth content and announcements
• Documentation - Feature reference and guides
• CMS Integration - Content management configuration

Next: FAQ →