Part 1 — +"Breaking changes and deprecation" page under releases to support the new processes

.github/actions/setup-r/action.yml

@@ -0,0 +1,33 @@
+name: "Setup R and install packages"
+description: "Sets up R and installs required packages for displaying interactive tables from .CSV"
+runs:
+  using: "composite"
+  steps:
+    - name: Set up R
+      uses: r-lib/actions/setup-r@v2
+      with:
+        r-version: '4.3'
+
+    - name: Cache R packages
+      uses: actions/cache@v3
+      with:
+        path: ${{ runner.os == 'Linux' && '/home/runner/work/_temp/Library' || runner.os == 'macOS' && '~/Library/R/4.3/library' }}
+        key: r-packages-${{ runner.os }}-${{ hashFiles('**/DESCRIPTION', '**/renv.lock') }}
+        restore-keys: |
+          r-packages-${{ runner.os }}-
+
+    - name: Install R packages
+      shell: bash
+      run: |
+        Rscript -e 'install.packages(c("DT", "readr", "stringr", "lubridate"), repos="https://cran.rstudio.com/")'
+
+    - name: Verify R installation
+      shell: bash
+      run: |
+        Rscript -e 'sessionInfo()'
+        which R
+
+    - name: Verify Quarto detects R
+      shell: bash
+      run: |
+        quarto check

.github/workflows/deploy-docs-prod.yaml

@@ -25,6 +25,9 @@ jobs:
 
       - name: Fetch Quarto
         uses: ./.github/actions/fetch-quarto
+
+      - name: Setup R environment
+        uses: ./.github/actions/setup-r
 
       - name: Render prod docs site
         run: |

.github/workflows/deploy-docs-staging.yaml

@@ -25,6 +25,9 @@ jobs:
 
       - name: Fetch Quarto
         uses: ./.github/actions/fetch-quarto
+
+      - name: Setup R environment
+        uses: ./.github/actions/setup-r
 
       - name: Render staging docs site
         run: |

.github/workflows/validate-docs-site.yaml

@@ -25,6 +25,9 @@ jobs:
     - name: Fetch Quarto
       uses: ./.github/actions/fetch-quarto
 
+    - name: Setup R environment
+      uses: ./.github/actions/setup-r
+
     - name: Render demo docs site
       run: |
           cd site

README.md

@@ -24,6 +24,12 @@ You need:
 - The Quarto extension for your IDE, such as [VS Code](https://marketplace.visualstudio.com/items?itemName=quarto.quarto)
 - For Windows operating systems, install the `make` command via [Cygwin](https://cygwin.com/install.html)
 
+### Additional dependencies
+
+Some interactive tables, such as our breaking changes and dependency history rely you have R and some R packages installed in order for you to be able to preview or render certain pages of the docs site locally.
+
+**Refer to the [Breaking changes and deprecations](site/releases/breaking-changes/README.md) guide** for more information on how to install R and set up these tables.
+
 ## How to contribute
 
 > [!IMPORTANT]

site/_quarto.yml

@@ -197,6 +197,8 @@ website:
           - releases/2023/release-notes-2023-jul-24.qmd
           - releases/2023/release-notes-2023-jun-22.qmd
           - releases/2023/release-notes-2023-may-30.qmd
+        - text: "Breaking changes & deprecations"
+          file: releases/breaking-changes/breaking-changes.qmd
         - text: "---"
         - text: "Fine Print"
         - about/fine-print/data-privacy-policy.qmd

site/releases/breaking-changes/README.md

@@ -0,0 +1,95 @@
+# Breaking changes and deprecations
+
+This guide walks you through how to add a breaking change or deprecation to our [~/releases/breaking-changes/breaking-changes.qmd](breaking-changes.qmd) history.
+
+## Before you begin
+
+In order to get Quarto display the neat interactive table in our HTML output, you need to have R and some dependencies installed in your environment.
+
+### Install R
+
+1. **Download and install R** from the Comprehensive R Archive Network: [CRAN](https://cran.r-project.org/index.html)
+    - If you're using VS Code, you may also want to install the following extensions: [R](https://marketplace.visualstudio.com/items?itemName=REditorSupport.r), [R Extension Pack](https://marketplace.visualstudio.com/items?itemName=Ikuyadeu.r-pack)
+2. **Open up an R terminal.** In VS Code you can press `CTRL/CMD + SHIFT + P` to open up the command palette, then type in and select `R: Create R Terminal`.
+
+### Install R dependencies
+
+In the R terminal, run:
+
+```bash
+install.packages("DT")
+install.packages("readr")
+install.packages("stringr")
+install.packages("lubridate")
+```
+
+These are the packages used to generate cool interactive tables from the yearly CSVs:
+
+- **[DataTables](https://rstudio.github.io/DT/)** — Displays a R data object as an HTML table.
+- **[readr](https://readr.tidyverse.org/)** — Parses the yearly `.csv` files for the table.
+- **[stringr](https://readr.tidyverse.org/)** — Parses markdown links in the `.csv` and turns them into HTML for the output table so they can be displayed properly.
+- **[lubridate](https://lubridate.tidyverse.org/)** — Parses and reformats the ISO 8601 date in the CSV into the Mon DD, YYYY format in the output table.
+
+## Creating entries
+
+### Add a year
+
+If you're adding the first entry for that year, you'll need to add that year to the history section first:
+
+#### Create the yearly CSV
+
+Make a copy of `~/releases/breaking-changes/year.csv` in the `~/releases/breaking-changes/history/` directory. For example:
+
+> `~/releases/breaking-changes/year.csv` > `~/releases/breaking-changes/history/2025.csv`
+
+> [!CAUTION]
+> Due to the way DataTables processes the input, there needs to be an empty row/line break at the end of the sheet.
+
+#### Insert CSV as table
+
+1. In `~/releases/breaking-changes/breaking-changes.qmd` under `<!-- CURRENT YEAR START -->`, insert the new year `h3` header. For example:
+
+    ```markdown
+    ### 2025
+    ```
+
+2. Then under that header, call the functions to display the interactive table for that year under a named and fenced `{r}` code block. For example:
+
+    ```R
+        ```{r 2025}
+        ## Render 2025.csv
+        my_data_2025 <- read_csv_data(2025)
+        my_data_2025 <- convert_markdown_links(my_data_2025)
+        my_data_2025 <- format_dates_in_data(my_data_2025)
+        render_table(my_data_2025)
+        ```
+    ```
+
+    Replace the year with the actual year you're intending to display.
+
+### Add an entry
+
+#### Create collateral
+
+You'll need the links for the release notes and any blog posts associated with the breaking change or deprecation to include in the table, so make sure those are published that first unless you want to fill them in at a later date.
+
+#### Enter an entry
+
+Open up the `.csv` for the year you want to update and create a new entry under the header row with the following information:
+
+| Column name | Content | Example |
+|---|---|---|
+| Change | Name of the feature being broken or deprecated | `Standard inputs are deprecated` |
+| Product area | Applicable variable for the ValidMind Library or ValidMind Platform | `{{< var validmind.developer >}} `|
+| Version | Associated library or platform version attached to the announcement prefaced by a `v` (Linked to release tags) | `v1.25.3` |
+| Type | Whether it's a breaking change or deprecation | `Deprecation` |
+| Date announced | ISO 8601 date of announcement | `2024-01-26` |
+| Release notes | Markdown format **HTML** link to the associated release notes enclosed by `""` | `"[Read](/releases/2024/2024-jan-26/highlights.html#standard-inputs-are-deprecated)"` |
+| Blog post | Markdown format link to the associated blog post enclosed by `""` | `"[Read](https://validmind.com/blog/)"` |
+| Date effective | ISO 8601 date of feature removal/deprecation | `2024-01-26` |
+
+> [!NOTE]
+> You can refer to the **[example `.csv`](example.csv)** for formatting guidance.
+>
+> If you're using VS Code, [Excel Viewer](https://marketplace.visualstudio.com/items?itemName=GrapeCity.gc-excelviewer) is a great extension to make editing `.csv` files more accessible.
+

site/releases/breaking-changes/breaking-changes.qmd

@@ -0,0 +1,36 @@
+---
+title: "Breaking changes and deprecations"
+date: last-modified
+# DON'T DISPLAY THE SOURCE CODE FOR THE TABLES ON THE PAGE
+execute:
+  echo: false
+---
+
+```{r import-script}
+# Import custom `breaking_changes` script
+source("breaking_changes.R")
+```
+
+## Definitions
+
+deprecation
+: - Feature not recommended for use.
+- May be removed in a future major release.
+
+breaking change
+: - Feature will be removed in a future major release.
+- Requires users to make a corresponding change to their code, settings, or workflows.
+
+## History
+
+<!-- CURRENT YEAR START -->
+
+### 2024
+
+```{r 2024}
+## Render 2024.csv
+my_data_2024 <- read_csv_data(2024)
+my_data_2024 <- convert_markdown_links(my_data_2024)
+my_data_2024 <- format_dates_in_data(my_data_2024)
+render_table(my_data_2024)
+```

site/releases/breaking-changes/breaking_changes.R

@@ -0,0 +1,71 @@
+# Load necessary libraries with output messages supressed
+suppressPackageStartupMessages(library(DT))
+suppressPackageStartupMessages(library(readr))
+suppressPackageStartupMessages(library(stringr))
+suppressPackageStartupMessages(library(lubridate))
+
+# Read CSV while preserving column names and treating all text as characters
+read_csv_data <- function(year) {
+  file_name <- paste0("history/", year, ".csv")
+  data <- read.csv(file_name, check.names = FALSE, stringsAsFactors = FALSE)
+  return(data)
+}
+
+# Cnvert Markdown-style links to proper HTML
+convert_markdown_links <- function(data) {
+  data[] <- lapply(data, function(column) {
+    column <- str_replace_all(column, "\\[(.*?)\\]\\((.*?)\\)", "<a href='\\2'>\\1</a>")
+    return(column)
+  })
+  return(data)
+}
+
+# Reformat ISO dates to Mon DD, YYYY
+format_date <- function(date_column) {
+  parsed_dates <- ymd(date_column)
+  formatted_dates <- format(parsed_dates, "%b %d, %Y")
+  return(formatted_dates)
+}
+
+# Apply date formatting to `Date announced` and `Date effective` columns
+format_dates_in_data <- function(data) {
+  if ("Date announced" %in% names(data)) {
+    data[["Date announced"]] <- format_date(data[["Date announced"]])
+  }
+  if ("Date effective" %in% names(data)) {
+    data[["Date effective"]] <- paste0(
+      "<span style='color: #92130cff;'>", format_date(data[["Date effective"]]), "</span>"
+    )
+  }
+  return(data)
+}
+
+# Render an interactive searchable and filterable table
+render_table <- function(data) {
+  datatable(
+    data,
+    options = list(
+      pageLength = 10, # Define default length of entries
+      dom = 'fltpi', # Table display options: Search/filter, length menu, the table istself, pagination, table info
+      initComplete = JS( # Filter `Product area`, `Version`, & `Type` using JavaScript
+        "function(settings, json) {
+          [1, 2, 3].forEach(function(index) {
+            var column = this.api().column(index);
+            var header = $(column.header()); // Keep original header text
+            var select = $('<br><select><option value=\"\">All</option></select>')
+              .appendTo(header) // Append instead of replacing
+              .on('change', function() {
+                var val = $.fn.dataTable.util.escapeRegex($(this).val());
+                column.search(val ? '^' + val + '$' : '', true, false).draw();
+              });
+            column.data().unique().sort().each(function(d, j) {
+              select.append('<option value=\"'+d+'\">'+d+'</option>')
+            });
+          }.bind(this));
+        }"
+      )
+    ),
+    escape = FALSE, # Allow HTML rendering
+    rownames = FALSE # Disable row numbering
+  )
+}

site/releases/breaking-changes/example.csv

@@ -0,0 +1,6 @@
+Change,Product area,Version,Type,Date announced,Release notes,Date effective
+ValidMind Library deprecation,{{< var validmind.developer >}},v00.0,Deprecation,YYYY-MM-DD,"[Read](url.html)",YYYY-MM-DD
+ValidMind Platform breaking change,{{< var validmind.platform >}},v00.0,Breaking change,YYYY-MM-DD,"[Read](url.html)","YYYY-MM-DD
+
+
+

site/releases/breaking-changes/history/2024.csv

@@ -0,0 +1,7 @@
+Change,Product area,Version,Type,Date announced,Release notes,Date effective
+Standard inputs are deprecated,{{< var validmind.developer >}},v1.25.3,Deprecation,2024-01-26,"[Read](/releases/2024/2024-jan-26/highlights.html#standard-inputs-are-deprecated)",2024-01-26
+Removed deprecated Python Library API methods,{{< var validmind.developer >}},v1.25.3,Breaking change,2024-01-26,"[Read](/releases/2024/2024-jan-26/highlights.html#removed-deprecated-methods)",2024-01-26
+
+
+
+

site/releases/breaking-changes/year.csv

@@ -0,0 +1,6 @@
+Change,Product area,Version,Type,Date announced,Release notes,,Date effective
+ValidMind Library deprecation,{{< var validmind.developer >}},v00.0,Deprecation,YYYY-MM-DD,"[Read](url.html)",YYYY-MM-DD
+ValidMind Platform breaking change,{{< var validmind.platform >}},v00.0,Breaking change,YYYY-MM-DD,"[Read](url.html)",YYYY-MM-DD
+
+
+