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 product release notes page

Add a new Release Notes page with RN next

1. Copy the existing content from partial_<prod>_rn_content.html.md to the existing doc page for that date (in place of the reference to the partial). For example, if the current release notes for Image & Video APIs product are for September 30, 2025, copy the content from partial_pm_rn_content.html.md to the existing rn_pm_09_30_2025.html.md file.
2. Copy the existing content from§ partial_<prod>_rn_content_next to the main partial_<prod>_rn_content.html.md (replacing the old content there).
3. Create a new markdown page for the new release notes page with the filename rn_<prod>_<date>.html.md, including the all the top matter (same as the one from the previous dated release notes page, except with the new date), and add it to the relevant place in the en.yml and the relevant product JSON menu file.
   • In the en.yml, besides adding a new entry for the new dated page, also update the date for the main product release notes entry and the latest dummy entry.
   • In the product JSON menu file, add the new dated page as the top child before latest + make it hidden, and remove the hidden entry on the previously hidden one.
     • After adding the new hidden page, the updated positions should be: 1- Latest, 2- New hidden page, 3- previously hidden page (now unhidden), 4) What was previously the 2nd visible page
     • Now move what's now become the 4th entry in the main list, to instead be the first under the archives structure.

       For example: If before adding the new page you had entries in the menu for Latest, Sep 3 (hidden), July 9, May 27, and then the archives, then after adding a new Oct 30 entry, you should have: Latest, Oct 30 (hidden), Sep 3 (unhidden), July 9, Archives with May 27 as the first child (moved from what became the 4th position above).

   • Menu file and location per product:
     • For Image & Video APIs product, use the programmable-media-menu.json file under the "id": "programmable_media_release_notes" parent.
     • For Assets (DAM) product, use the digital-assets-management-menu.json file under the "id": "digital_asset_management_release_notes" parent.
     • For MediaFlows, use the more-products-menu.json file under the "id": "mediaflows_release_notes" parent.
   • See examples of the en.yml and JSON menu file structure below.
4. Add new entries for the new date to the RSS feed and archive table entry.
   • For both the archives table entry - copy the previous entry as a new top entry and update date. If you don't know the description yet, can update it in both places to "TBD".
   • If the archive page §entry is the first one in a new year, then first create a new year H2 in the archives page, and a new table under it with one entry for the new date.
   • In the RSS feed, ensure the day of the week is an accurate 3-letter abbreviation for the new date.
   • See example of the RSS feed entry structure below.
5. Merge to staging and check:
   • Make sure the main release notes page now contains the new content & everything in the menu looks and opens the pages as expected.
   • Make sure the new entry in the archive table is there & the link goes to the correct page.
   • THe "NEXT VERSION (STAGING)" entry in the menu (which shows the rn_next content) should remain the 4th entry just above the "Previous Releases" parent. It should only exist in staging.
   • The "RN Next" entry in the archive table should remain the last entry in the current year. If you created a new table for a new year, manually move the RN Next entry to the bottom of the new year's table and push that change only on staging. It should only exist in staging.
   • Make sure you see the RSS notification in the release-notes-staging slack channel.

Add a new Release Notes page (old process)

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)

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)

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

Adding RSS feed entries

The RSS files are in the format of cloudinary--release-notes.yml, with the being the product abbreviation name in lowercase (e.g. "pm", "dam", "mf").

Structure example

RSS Item Fields

• Item title - The date when you expect top publish the RN
• 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)

Adding an RN entry to the Menu JSON

Structure example

Adding an RN entry to the en.yml

Structure example

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!

Release Notes tips & guidelines

Use Cursor to write release notes entries

Prerequisite: Make sure you've set the cloudinary-docs.mdc & content-style.mdc rules files to Apply Intelligently.

1. In the cursor chat, attach the following files:
   
   • The markdown page containing the documentation from your page
   • The rn_next partial file where you want to add the content
   • The existing rn_content partial file (should contain the previously released release notes)

2. Adjust the prompt below to relate to your feature & where you want to add the item within your release notes: