From fe4697a03265a510a4b396cdbdd5e3b928ffdd53 Mon Sep 17 00:00:00 2001 From: Dan Brady Date: Fri, 7 Mar 2025 15:56:52 -0500 Subject: [PATCH 1/3] Initial draft --- README.md | 66 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) diff --git a/README.md b/README.md index 0d1ca169a..990cdca1d 100644 --- a/README.md +++ b/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. From 0da7de9694632807ccc63cb0e8b4d52f4b8ffefc Mon Sep 17 00:00:00 2001 From: Dan Brady Date: Fri, 7 Mar 2025 16:01:32 -0500 Subject: [PATCH 2/3] update note syntax --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 990cdca1d..6314f7bdf 100644 --- a/README.md +++ b/README.md @@ -134,8 +134,8 @@ Within this project is the ability to automate the display of the latest release ### 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. +> [!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. @@ -157,8 +157,8 @@ These scripts rely on releases to be created in the [component-library repo](htt ### How to Update the What's New Page -[!NOTE] -Be sure your local environment is not running before getting the latest updates. +> [!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: From 4012359f4d3147e03318d7e77aa69785395c1ee4 Mon Sep 17 00:00:00 2001 From: Dan Brady Date: Fri, 7 Mar 2025 16:06:04 -0500 Subject: [PATCH 3/3] add additional steps --- README.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 6314f7bdf..6fc434952 100644 --- a/README.md +++ b/README.md @@ -162,14 +162,16 @@ Within this project is the ability to automate the display of the latest release 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 -... -``` + ``` + ... + 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 + ... + ``` +3. Once Jekyll completes building, navigate to the What's new page in a browser to confirm the latest releases are visible. +4. Submit a PR with the updated JSON files. ## Additional Testing