Release Notes Management

Overview

This guide covers the technical process for managing Cloudinary release notes, including file structure, archiving, and RSS feed management.

Adding a New Release Notes File

Step 1: One-time Setup (if doesn't exist)

Create the main file partial: - Create: _partial_<prod>_rn_content.html.md - Add this partial to the main RN file and to the upcoming date archive file

Step 2: Create Archive File for the Version You're About to Create

1. Duplicate the previous archive file

   • Update filename: rn_<prod>_<planned_release_date>
   • Update the date in the front matter (using 3-letter month format)

2. Add the new archive file to en.yml

   • Copy the previous entry and update the dates (full month spelling)
   • Update the dates for the main release notes en.yml entry and the latest dummy entry

3. Copy the entire old content from the content partial to the previous 'archive' file

   • Copy _partial_<prod>_rn_content and paste it below the autotoc entry, in place of the reference to the partial
   • In the relevant product JSON, add the created archive file as the top child before latest + hidden
   • Remove hidden from the previous one
   • Move what's become the 4th one to be the first under the archives structure (latest at the top)

Menu JSON Structure Example:

Step 3: Update the RN Content Partial

Update the content partial with new content:

• Keep the Notifications section as is
• Change the updated_date entry in the frontmatter at the top of the MD file to the expected release date
  • Example: updated_date: Jan-30-2022

En.yml updates:

• Update the title of the main file to the same expected date
• Update to the same date in the rn_<prod>_latest dummy menu entry title
  • Example: "Latest: Jan 30, 2023"

Step 4: Update the Archives Page

Update the archives page (rn_<prod>_archives):

• Change the updated_date entry in the frontmatter at the top of the MD file to the expected release date of the new release notes
  • Example: updated_date: Jan-30-2022
• Add an entry to the top of the table with the date of the last release note (linking to the release note in the archives) and the description taken from the RSS feed

Step 5: Update the RSS Feed File

Update RSS file (rss/cloudinary-<prod>-release-notes.yml):

• Add a new 'item' entry above the previous one (don't remove previous)

RSS Structure Example:

RSS Item Fields:

• Item title - The date when the RN is supposed to be published
• Link - Keep as is
• Description - 1-2 sentence teaser listing the main new features and any other info that might interest our target audience to want to read them
• pubDate - Same as the date in the item title, but make sure the day of the week is accurate for the date (3 letter abbreviation)

Test on Staging: - Check that RSS updates work in staging RSS channel (TBD)

Final Pre-Release Date Verification

Before the final release, double-check the date matches the actual deployment date in the following places:

En.yml:

• Date in main entry title
• Date in dummy latest title

Main RN file:

• updated_date value in the frontmatter at the top of the MD page

Archives (dated) RN file:

• If you change the date of the RN, you need to rename this file itself and then update the references to the file in the TOC JSON, en.yml, and archives markdown page
• updated_date value in the frontmatter at the top of the MD page and date of latest entry

RSS YAML file:

• In the title of the new entry
• In the pubDate of the main entry
• IMPORTANT: Make sure the day of the week is accurate for the new date!