Release notes

Setting up the release notes feature

The release notes feature is toggled by creating a conventionally named file src/content/releases.mdx. The file is written like a regular content page. The Docs-Kit is automatically generating the release notes list below the content of that file and is applying a custom layout with filters for finding release notes.

See the test site for an example.

Creating a new release note

Release note files can be found in src/releases and are written in MDX like regular content. You can also place files in folders to better organize the release notes.

The files' location does not imply the URL like for content. The URL is built from the frontmatter fields for date and title. (The URL can also be customized by the slug frontmatter. Read more about available frontmatters below.) This way you can reorganize the files without changing the URL of the release note.

To learn the full release note file format including the full specification of the frontmatter fields, see the specification by example file.

Template

When not using the CLI tool to create a release note, you can use this template:

---
date: 2020-01-01
title: (TEMPLATE) TITLE
description:
  | # title content and what this is good for //  max 256 characters // for MC, RSS and other feeds
  (TEMPLATE) DESCRIPTION
type: enhancement # feature | fix | enhancement | announcement | deprecation
topics:
# uncomment matching topics. Stay focused.
#  - Products
#  - Product List
#  - Categories
#  - Carts
#  - API Clients
#  - Settings
---

FooBar Intro Line: What this is good for (like description)

- [API] FooBar

<!--more-->

A longer explanation here that is just shown on the details page.
If there is no more, remove the marker above, too.

Available frontmatters:

• date (date, required): A YYYY-MM-DD date format (not a text, it's parsed as an ISO date).
• title (string, required): The title for the website.
• description (string, required): Max 256 characters plain text containing the change and its advantage ("tweet-able" and for RSS). 256 = 280 twitter minus 23 for a link. Do not imply the title, this text is used stand-alone in Merchant Center and other feed recipients. It must convey the value proposition and key change topic.
• type (string | string[], required): Must be either feature (for "New feature"), enhancement (for "Enhancement"), fix (for "Resolved issue"), announcement (for "Announcement") or deprecation (for "Deprecation").
• orderHint (number, optional): Sorts release notes that share the same release date by adjusting the timestamp. Uses an ascending order with 1 being the most recent release note and 20 being the oldest. This logic works across multiple microsites. If you have multiple release notes from different microsites with the same release date, add this frontmatter to the respective release notes to sort them accordingly from 1 to 20. Values above 20 will be ignored.
• topics (array of string, optional): YAML array of free to choose text entries. The Filter UI may be constrained to pre-defined topics.
• published (boolean, optional, defaults to true): false prevents rendering of the release in the site. Should not be used in the main documentation, reserved for atypical situations. Not included in the template.
• slug (string, optional, defaults to $date-$title (slugified)): Allows overriding the autogenerated URL slug. Should not be used in the main documentation, reserved for migrating legacy docs.
• product (string, optional): Used in the release notes search to filter by product. If set, it overrides the product defined in the website gatsby-configure.mjs. Please note that in case an array is defined, just the first value is used for filtering purposes.
• productArea (string, optional): Used in the release notes search to filter by product area. If set, it overrides the title defined in the website gatsby-configure.mjs.
• hideProductLabels (boolean, optional): Used to hide the product and productArea labels on the release note details and list page.

Release note's search indexing

Each time a feature branch containing changes to any file existing in the website's releases directory is merged into main, it will trigger a full reindex of all the release notes.