From 60551ff9f1b6d9b24c7b2afbdae8412931f2eaa7 Mon Sep 17 00:00:00 2001
From: st0012 <stan001212@gmail.com>
Date: Mon, 23 Feb 2026 20:23:46 +0000
Subject: [PATCH] Add CI check for RI backward compatibility
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Prevents regressions like #1535 where Marshal format changes
(e.g., Heading Struct → class) break ri when reading data
generated by older RDoc versions.

The check generates ri data using old RDoc gem versions, then
installs the current RDoc and verifies it can still read that data.
---
 .github/workflows/ri-backward-compat.yml | 69 ++++++++++++++++++++++++
 1 file changed, 69 insertions(+)
 create mode 100644 .github/workflows/ri-backward-compat.yml

diff --git a/.github/workflows/ri-backward-compat.yml b/.github/workflows/ri-backward-compat.yml
new file mode 100644
index 0000000000..ec8002aafe
--- /dev/null
+++ b/.github/workflows/ri-backward-compat.yml
@@ -0,0 +1,69 @@
+name: RI Backward Compatibility
+
+on:
+  push:
+    branches:
+      - '**'
+      - '!dependabot/**'
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  ri-backward-compat:
+    name: RI reads data generated by RDoc ${{ matrix.old_rdoc }}
+    strategy:
+      fail-fast: false
+      matrix:
+        old_rdoc: ['6.5.0', '6.9.0', '7.0.2']
+    runs-on: ubuntu-latest
+    env:
+      RI_DATA_DIR: /tmp/ri_data
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@09a7688d3b55cf0e976497ff046b70949eeaccfd # v1.288.0
+        with:
+          # Must use Ruby 3.x — on Ruby 4.0, Heading is always a Class while old
+          # RDoc versions serialized it as a Struct, so the test would always fail
+          # regardless of whether the current code is correct.
+          ruby-version: '3.4'
+      - name: Generate ri data with old RDoc
+        run: |
+          gem install rdoc -v ${{ matrix.old_rdoc }} --no-document
+          ruby -e '
+            gem "rdoc", "${{ matrix.old_rdoc }}"
+            require "rdoc/rdoc"
+            puts "Generating ri data with RDoc #{RDoc::VERSION}"
+            RDoc::RDoc.new.document(["--ri", "--op", ENV["RI_DATA_DIR"], "--quiet", "lib/"])
+          '
+      - name: Install current RDoc
+        run: |
+          gem build rdoc.gemspec
+          gem install rdoc-*.gem --no-document
+      - name: Verify current ri can read old data
+        run: |
+          ruby -e '
+            require "rdoc"
+            puts "Reading ri data with RDoc #{RDoc::VERSION}"
+
+            store = RDoc::Store.new(RDoc::Options.new, path: ENV["RI_DATA_DIR"], type: :extra)
+            store.load_cache
+
+            modules = store.module_names
+            errors = []
+
+            modules.each do |mod_name|
+              store.load_class(mod_name)
+            rescue => e
+              errors << [mod_name, e]
+              warn "FAIL: #{mod_name} - #{e.class}: #{e.message}"
+            end
+
+            if errors.empty?
+              puts "All #{modules.size} modules loaded successfully"
+            else
+              abort "#{errors.size} of #{modules.size} modules failed to load"
+            end
+          '