Checking access…

Skip to main content
Version: v2

Release Notes Maintenance Guide

Use this guide when adding or updating content under /docs/release-notes.

Target Structure​

Keep the release-notes area organized by content intent:

  • changelog: chronological release updates.
  • migration: hands-on migration runbooks.
  • v1-v2-api-comparison: side-by-side contract differences.
  • index.md: section landing page only.

Avoid placing additional long-form pages directly under /docs/release-notes unless they are section entry pages.

Naming Rules​

Use predictable, stable file names:

  • Use lowercase kebab-case file names.
  • Use singular nouns for endpoint comparison pages when one resource is represented, for example webhook.mdx instead of webhooks.mdx.
  • Keep folder names aligned to domain names already used in navigation.
  • Prefer stable slugs in frontmatter when moving files so public links do not break.

Use explicit positions to keep navigation stable as content grows:

  • Set position in each category category.json.
  • Set sidebar_position in each document frontmatter.
  • Do not rely on implicit alphabetical ordering.
  • Keep entry pages first, then how-to guides, then references.

Authoring Rules For New Release Notes Content​

Before adding a new file, decide the correct section:

  • If it describes what changed by date, place it in changelog.
  • If it explains how to perform a migration safely, place it in migration.
  • If it compares v1 and v2 request or response contracts, place it in v1-v2-api-comparison.

For comparison pages:

  • Keep request, response, and webhook pages in a consistent order.
  • Reuse title patterns such as Domain - Request or Domain - Response.
  • Keep iframe embed titles consistent and descriptive.

Maintenance Checklist​

For every release-notes change:

  • Confirm the file is in the correct section folder.
  • Confirm slug values remain stable after moves.
  • Confirm sidebar_position and category position are explicit.
  • Confirm links from release-notes index and migration pages remain valid.
  • Run docs structure lint on changed files.
  • Run a quick broken-link check for moved pages.