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.
   • After copying the content, move the existing {autotoc} and {/autotoc} tags that were already there below the first H2 entry in the copied content. This ensures there won't be an extra HR line before the H2.

2. Copy (not move) the existing content from partial_<prod>_rn_content_next to the main partial_<prod>_rn_content.html.md. Do not remove the content from rn_content_next.

   • The content you just promoted may have been drafted weeks earlier, by different people and tools, and hasn't necessarily been proofread as a whole. Before moving on, read it end to end and check it against the Content Style Guide: Oxford commas in lists of three or more, no em-dashes, consistent product-name capitalization, and headings that lead with value. Then run Vale over the partial and clear anything it flags. Note that Vale does not check for the Oxford comma, so that one is on you.

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 file, update THREE entries with the new date:

  • Add a new entry for the new dated page (e.g., rn_pm_10_30_2025)
  • Update the main product release notes entry (e.g., programmable_media_release_notes: title:)
  • Update the latest dummy entry (e.g., rn_pm_latest: title:)

  Example for Oct 30, 2025: - programmable_media_release_notes: title: 'Cloudinary Image & Video release notes: October 30, 2025' - rn_pm_latest: title: "Latest: October 30, 2025" * 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. * The main list always keeps three dated entries below Latest: the new hidden page, plus the two most recent published ones. Adding a new page therefore pushes the oldest of the three into the archives. * After adding the new hidden page, the main list reads: 1- Latest, 2- New hidden page, 3- Previously hidden page (now unhidden), 4- The newer of the two remaining visible pages, 5- The older of the two remaining visible pages. * Now move entry 5, the oldest dated entry in the main list, to be the first child under the archives structure. Entries 1 to 4 keep their positions.

  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 out of the main list).

  * 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 mediaflows-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. * IMPORTANT: In the RSS feed, ensure the day of the week is an accurate 3-letter abbreviation for the new date. Use the date command to get the correct day of the week for the provided date. * See example of the RSS feed entry structure below.

1. Clear (completely delete) all H3 and lower content inpartial_<prod>_rn_content_next.html.md. Keep all the H2 headings. If any standard H2 headings were deleted, add them back. Conversely, if any special one-time H2 headings were added, delete them.

   • For Image and Video APIs product, the cleaned version of this partial file should contain exactly the following H2s: ## Cloudinary Image, ## Cloudinary Video, ## Asset management and upload, ## Account management, ## Docs and demo apps, ## Coming soon, ## Announcements
   • For Assets (DAM) product, the cleaned version of this partial file should contain exactly the following H2s: ## New features, ## Enhancements, ## Fixes, ## Announcements, ## Coming soon
   • For MediaFlows product, the cleaned version of this partial file should contain exactly the following H2s: ## New features, ## Enhancements, ## Documentation, ## Announcements, ## Coming soon

2. Verification Checklist - Before proceeding, verify you have completed ALL of these steps:

{checklist} - [ ] Copied content from partial_<prod>_rn_content.html.md to previous dated file - [ ] Copied (not moved)content from partial_<prod>_rn_content_next.html.md to main partial_<prod>_rn_content.html.md. (the ...rn_content_next file should remain unchanged.) - [ ] Proofread the promoted content against the Content Style Guide and ran Vale over it - [ ] Every entry in the new content partial has a JIRA ID comment below its H3 heading - [ ] Created new rn_<prod>_<date>.html.md file - [ ] Added new dated entry to en.yml - [ ] Updated main product release notes title in en.yml** (e.g., programmable_media_release_notes: title:) - [ ] Updated latest dummy entry in en.yml (e.g., rn_pm_latest: title:) - [ ] Updated menu JSON file structure - [ ] Added RSS feed entry with correct day of week - [ ] Updated archives page with new entry - [ ] Updated updated_date in all relevant files - [ ] Clear H3 sections in partial_<prod>_rn_content_next.html.md. Keep all the H2 headings, including restoring any standard ones that were deleted and removing any special one-time ones that were added. {/checklist}

1. 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.
   • Make sure the RSS feed entry exists and that the day of the week is accurate for the new date.
   • THe "NEXT VERSION (STAGING)" entry in the menu (which shows the rn_next content) should remain as 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 leading with the value of the main new features, phrased the same way as the entry headings on the page (see Lead with the value, not the mechanics). Keep it identical to the archives table description for the same date.
• 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

Lead with the value, not the mechanics

Every heading and opening line should answer "why would I care?" before "what is it?" In other words, tell the reader what value the change brings before explaining what the feature does or how to use it. In the past, first drafts, especially AI-generated ones, defaulted to describing the implementation. Instead you should write them focussed on what the end-user gains.

Headings. A bare feature name makes readers work out the relevance for themselves. Name the outcome instead:

• People Search API becomes Manage People Search programmatically with the new API
• New third-party sources for the Upload Widget becomes Let users upload from Box, OneDrive, and SharePoint
• Source URL available to the eval upload parameter becomes Track where remote uploads came from

First sentence. Open on the payoff: what the reader can now do, or what pain goes away. Keep the mechanics as support in the sentences that follow.

Too mechanical (describes the feature): The AI Video Analysis API (Beta) lets you generate a visual transcription of a video: timestamped, natural-language descriptions of what's visible on screen.

Better (opens on the problem it solves): Your videos are invisible to search engines, tagging pipelines, and screen readers unless something describes what's actually on screen. The AI Video Analysis API (Beta) generates a visual transcription: timestamped, natural-language descriptions of what appears in each part of the video.

Rules for every entry:

• Name a concrete scenario, not an abstract capability. Avoid the first plausible-sounding reason and pick the one that's actually true for how the feature gets used.
• Cut filler qualifiers. "in a more intuitive way", "for better usability", and "to improve your workflow" say nothing.
• One capability per entry. Don't bundle unrelated changes under a single heading.
• Save exhaustive configuration detail for the linked reference doc. The entry sells the change, the reference documents it.
• If the feature already existed and the news is a new way to use it, say so. Framing a Console feature's new API as brand new misleads the readers who already use it.

RSS and archives descriptions. These are written from the entries, so they inherit the same rule. Whenever you rewrite headings or reorder entries, update both descriptions to match: they should lead with the same features the page leads with, in the same value-focused language. Keep the two descriptions identical to each other.

Treat the first draft as a draft. Release notes copy is worth a second pass once you see it rendered.

Include the JIRA ID in each entry

Every release notes entry carries the JIRA ID(s) of the work it describes, in an internal markdown comment placed directly below the entry's H3 heading, with no blank line in between. For example:

• Separate multiple IDs with commas, as above.
• Keep a blank line between the comment and the entry's first paragraph.
• If the entry has no ticket, write the reason instead, for example [//]: # (No JIRA - AX launch).

The comment renders as nothing on the published page, so the IDs stay internal. Its purpose is traceability: anyone reviewing a published entry can find the work that produced it.

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: