Initial draft

Author: danbrady

README.md

@@ -105,6 +105,72 @@ Then click the "Re-run all jobs" button at the top of the page:
 
 ![The "Re-run all jobs" button for running a Github workflow again](https://github.com/department-of-veterans-affairs/vets-design-system-documentation/blob/main/src/images/readme/re-run-workflow-button.png?raw=true)
 
+
+## Updating the What's New Page with Changelogs
+
+Within this project is the ability to automate the display of the latest releases from the VADS component library and design system documentation repositories, along with recent changes from the component library's Figma file. This ensures the "What's New" page in the documentation site is always up-to-date.
+
+### Features
+
+* **Automated Release Fetching:** Retrieves and displays the latest releases from:
+    * [VADS Component Library repository](https://github.com/department-of-veterans-affairs/component-library)
+    * [design.va.gov repository](https://github.com/department-of-veterans-affairs/vets-design-system-documentation)
+* **Embedded Figma Changelog:** Integrates the changelog frame from the Component Library Figma file.
+* **Dynamic "What's New" Updates:** Automatically updates the "What's New" page with the latest release notes.
+
+### File Structure
+
+* `json_data_cache/` - Stores fetched release data in JSON format, enabling Jekyll to access it during site builds.
+* `src/`
+    * `_about/`
+        * `whats-new.md` - The page that displays the latest updates.
+    * `_includes/`
+        * `_github_markdown_parser.html` - Parses each release from the `data` object into a `va-card` and performs text manipulation for a more user-friendly display.
+    * `_plugins/`
+        * `jekyll_get_json.rb` - A Jekyll plugin that fetches and stores JSON data from GitHub, making it available to Jekyll's `data` object.
+        * `vads.rb` - Provides a custom Jekyll/Liquid filter for applying regular expression-based string transformations to release notes, enhancing readability.
+* `_config.yml` - Configuration file for Jekyll, defining repository URLs and Figma file details.
+* `package.json` - Contains the `yarn run update-releases` script, a shortcut for updating release data.
+
+### How Jekyll Displays the Latest Releases
+
+[!NOTE]
+These scripts rely on releases to be created in the [component-library repo](https://github.com/department-of-veterans-affairs/component-library) and [design.va.gov repo](https://github.com/department-of-veterans-affairs/vets-design-system-documentation). Before running the scripts, be sure that a release is made and tagged appropriately.  
+
+1.  **JSON Data Retrieval:**
+    * When Jekyll builds the site, it checks for JSON files (defined in `_config.yml`) in the `json_data_cache/` folder.
+    * If the files do exist, the cached files are used preventing repeated requests to Github.
+    * If the files do not exist, it fetches the latest release notes from GitHub and stores it as JSON in the `json_data_cache/` folder.
+2.  **Data Loading:**
+    * The JSON data is loaded into Jekyll's `data` object upon building the site.
+3.  **"What's New" Page Generation:**
+    * The `whats-new.md` page uses the `_github_markdown_parser.html` include to process the release data from the `data` object and passes that into `json`.
+    * The `num_recent_releases` parameter controls how many of the most recent releases are shown.
+    * Example:
+         ```
+         {% include _github_markdown_parser.html json=site.data.site_releases num_recent_releases=3 %}
+         ```
+4.  **String Manipulation:**
+    * The `vads.rb` custom filter applies regular expression transformations to the release notes (`json`), improving readability.
+5.  **Figma Data:**
+    * The Figma changelog frame is simply embedded into the page with an iframe direct from the Figma Component Library. Updates are in real time. 
+
+### How to Update the What's New Page
+
+[!NOTE]
+Be sure your local environment is not running before getting the latest updates.
+
+1. Run `yarn run update-releases`. This script deletes the `json_data_cache/` folder and then fetches the latest release data from GitHub, ensuring you have the most current information. It will then continue to build the site normally.
+2. If release data is fetched, you should see this captured in the logs as the site builds: 
+```
+...
+Generating... 
+* Caching https://api.github.com/repos/department-of-veterans-affairs/vets-design-system-documentation/releases in json_data_cache/site_releases.json
+* Caching https://api.github.com/repos/department-of-veterans-affairs/component-library/releases in json_data_cache/component_library_releases.json
+   Jekyll Feed: Generating feed for posts
+...
+```
+
 ## Additional Testing
 
 This project is tested with BrowserStack.