Changelog and Release Notes Format

Why a structured changelog matters

Teams adopting Optimizely products need to know what changed, when, and whether it affects them. A well-structured changelog lets developers filter by the products they use, identify breaking changes before upgrading, and plan migration work. The portal’s changelog system uses frontmatter metadata to power filtering and search across all release notes.

---

Changelog frontmatter schema

Every changelog entry is an MDX file with structured frontmatter. The portal validates this schema at build time.

Required fields

---
title: "CMS SaaS 2026.3 Release Notes"
description: "New content approval workflows, Graph sync performance improvements, and deprecation of legacy media API."
type: changelog
domain: content-management        # Primary domain
product: cms-saas                  # Single product this release applies to
version: '2026.3'                  # Version string
release_date: '2026-03-15'        # ISO date of the release
status: published
last_reviewed: '2026-03-15'
---

Optional fields

breaking_changes: true              # Whether this release includes breaking changes
deprecated_features:                 # List of deprecated features
  - 'Legacy Media Upload API'
  - 'Classic Editor mode'
security_fixes: true                 # Whether security patches are included
highlights:                          # Top 3-5 changes for summary display
  - 'Content approval workflows'
  - 'Graph sync 40% faster'
  - 'Legacy media API deprecated'
min_upgrade_version: '2025.12'       # Minimum version required before upgrading
migration_required: true             # Whether manual migration steps are needed

Field reference

Field	Type	Required	Description
title	string	Yes	Release title, typically “[Product] [Version] Release Notes”
description	string	Yes	One-sentence summary of the release
type	'changelog'	Yes	Must be changelog
domain	string	Yes	Primary domain (e.g., content-management, experimentation)
product	string	Yes	Product slug this release applies to
version	string	Yes	Version identifier
release_date	string (ISO date)	Yes	Date the release was published
breaking_changes	boolean	No	Whether the release contains breaking changes (default: false)
deprecated_features	string[]	No	List of features deprecated in this release
security_fixes	boolean	No	Whether security patches are included (default: false)
highlights	string[]	No	Top changes for summary cards
min_upgrade_version	string	No	Minimum version required before upgrading to this release
migration_required	boolean	No	Whether manual migration steps are needed (default: false)
status	string	Yes	draft or published
last_reviewed	string (ISO date)	Yes	Date the page was last reviewed

---

Content structure

Changelog entries follow a consistent structure to make scanning efficient.

Recommended sections

## Highlights

Brief summary of the most important changes (3-5 bullets).

## New features

### Feature name

Description of the feature, why it was added, and how to start using it.

## Improvements

### Improvement name

What changed and what the user-facing impact is.

## Bug fixes

- Fix for [issue description] (#issue-number)
- Fix for [issue description] (#issue-number)

## Breaking changes

### Change name

**What changed:** Description of the breaking change.
**Why:** Reason for the change.
**Migration:** Steps to update your implementation.
**Deadline:** When the old behavior will be removed (if applicable).

## Deprecations

### Feature name

**Deprecated in:** This release.
**Removal planned:** [Version or date].
**Migration path:** What to use instead.

## Security

- [CVE-YYYY-NNNNN]: Description and severity.

## Known issues

- Description of known issue and workaround.

Writing guidelines for changelog entries

• Lead each change with the user impact, not the implementation detail.
• For breaking changes, always include migration steps.
• Link to relevant guides or reference pages for detailed instructions.
• Use past tense for completed changes (“Added”, “Fixed”, “Removed”).
• Include issue or ticket numbers where available.

---

Filtering by product

The changelog index page supports filtering by product, domain, and change type.

URL filter parameters

/changelog/?product=cms-saas
/changelog/?product=experimentation-web&breaking=true
/changelog/?domain=content-management&year=2026

Parameter	Type	Description
product	string	Filter by product slug
domain	string	Filter by domain
breaking	boolean	Show only releases with breaking changes
security	boolean	Show only releases with security fixes
year	number	Filter by release year

Valid product slugs

cms-saas, cms-paas, experimentation-web, experimentation-feature, odp, cmp, personalization, graph, opal, opti-id, analytics, commerce-connect, commerce-classic

---

File organization

Changelog entries live under src/content/docs/reference/configuration/ or a dedicated changelog/ directory (if configured). Name files using the pattern:

{product}-{version}.mdx

Examples:

• cms-saas-2026-3.mdx
• experimentation-web-2026-q1.mdx
• graph-2026-03.mdx

---

Example entry

See Sample Changelog Entry for a complete example of a changelog page with all sections.

---

Related resources

• Sample Changelog Entry — A complete example changelog page
• Content Standards — Overall writing standards for the portal
• Contributing — How to submit changelog entries