Merge branch 'master' into binford2k-patch-2

Author: binford2k

.github/workflows/build.yaml

@@ -35,7 +35,7 @@ jobs:
       tag: '${{ steps.set-params.outputs.tag }}'
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
         with:
           ref: '${{ inputs.ref }}'
           fetch-depth: 1
@@ -57,14 +57,17 @@ jobs:
 
   build:
     runs-on: ubuntu-24.04
-    timeout-minutes: 5
+    # references:all clones and generates docs for three products and the
+    # component-version tasks make live GitHub API calls, so the build is network-
+    # variable and runs ~5 min; give headroom above the previous tight 5-min cap.
+    timeout-minutes: 10
     needs:
       - setup
     env:
       ARCHIVE: '${{ needs.setup.outputs.archive }}'
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
         with:
           ref: '${{ inputs.ref }}'
           fetch-depth: 1
@@ -79,12 +82,19 @@ jobs:
         env:
           GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
         run: |
-          bundle exec rake references:openfact INSTALLPATH=docs
-          bundle exec rake references:openvox INSTALLPATH=docs
-          bundle exec rake references:openbolt INSTALLPATH=docs
-          # Refresh the openvox-agent release-contents table from upstream pins.
-          # Falls back to the committed _data file if the GitHub API is unreachable.
+          # Build each product/version's reference docs from the pin table in
+          # _data/products.yml into its collection (see `rake references:all`).
+          bundle exec rake references:all INSTALLPATH=docs
+          # Refresh the component-version tables (agent, server, openvoxdb) from
+          # upstream pins. Each falls back to its committed _data file if the
+          # GitHub API is unreachable, so a transient failure never breaks the build.
           bundle exec rake references:agent_versions || echo 'agent_versions refresh failed; using committed _data'
+          bundle exec rake references:server_versions || echo 'server_versions refresh failed; using committed _data'
+          bundle exec rake references:openvoxdb_versions || echo 'openvoxdb_versions refresh failed; using committed _data'
+          bundle exec rake references:openbolt_versions || echo 'openbolt_versions refresh failed; using committed _data'
+          # Refresh the supported-platforms table from the shared-actions
+          # platforms.json, falling back to the committed _data file if unreachable.
+          bundle exec rake references:supported_platforms || echo 'supported_platforms refresh failed; using committed _data'
           bundle exec jekyll build
       - name: Archive website
         run: |

.github/workflows/deploy.yaml

@@ -40,7 +40,10 @@ jobs:
 
   ship:
     runs-on: ubuntu-24.04
-    timeout-minutes: 1
+    # Pulling and extracting the full-site archive, uploading the Pages artifact,
+    # and the GH Pages deployment together exceed 1 minute as the site grows, so
+    # give the job headroom above the previous tight 1-minute cap.
+    timeout-minutes: 5
     needs:
       - setup
     permissions:

.github/workflows/markdownlint.yml

@@ -15,72 +15,21 @@ jobs:
   markdown-lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0  # required to resolve base.sha for PR diff comparison
-      - name: Find changed Markdown files
-        id: changed-markdown
+      - uses: actions/checkout@v7
+      - name: List tracked Markdown files
+        id: tracked-markdown
         shell: bash
+        # Lint git-tracked files only. This lints the canonical versioned dirs
+        # once and skips the `_latest` symlinks (git stores them as single
+        # symlink entries, so a filesystem glob would double-lint their targets).
+        # It also excludes generated reference docs, which are gitignored.
         run: |
-          case "${GITHUB_EVENT_NAME}" in
-            pull_request)
-              base_sha="${{ github.event.pull_request.base.sha }}"
-              head_sha="${GITHUB_SHA}"
-              ;;
-            push)
-              base_sha="${{ github.event.before }}"
-              head_sha="${GITHUB_SHA}"
-              ;;
-            *)
-              # workflow_dispatch: lints only files changed in the most recent commit, not the full branch
-              # || true handles initial commits with no parent
-              base_sha="$(git rev-parse "${GITHUB_SHA}^" 2>/dev/null || true)"
-              head_sha="${GITHUB_SHA}"
-              ;;
-          esac
-
-          if [[ -z "${base_sha}" || "${base_sha}" =~ ^0+$ ]]; then
-            base_sha="$(git rev-list --max-parents=0 "${head_sha}")"
-          fi
-
-          git diff --name-only --diff-filter=A    "${base_sha}" "${head_sha}" -- '*.md' '*.markdown' > added-markdown-files.txt
-          git diff --name-only --diff-filter=CMRT "${base_sha}" "${head_sha}" -- '*.md' '*.markdown' > modified-markdown-files.txt
-
-          if [[ -s added-markdown-files.txt ]]; then
-            echo "has_added=true" >> "${GITHUB_OUTPUT}"
-            {
-              echo 'added_files<<EOF'
-              cat added-markdown-files.txt
-              echo 'EOF'
-            } >> "${GITHUB_OUTPUT}"
-          else
-            echo "has_added=false" >> "${GITHUB_OUTPUT}"
-          fi
-
-          if [[ -s modified-markdown-files.txt ]]; then
-            echo "has_modified=true" >> "${GITHUB_OUTPUT}"
-            {
-              echo 'modified_files<<EOF'
-              cat modified-markdown-files.txt
-              echo 'EOF'
-            } >> "${GITHUB_OUTPUT}"
-          else
-            echo "has_modified=false" >> "${GITHUB_OUTPUT}"
-          fi
-
-      - name: No changed Markdown files
-        if: steps.changed-markdown.outputs.has_added != 'true' && steps.changed-markdown.outputs.has_modified != 'true'
-        run: echo "No changed Markdown files to lint."
-
-      - name: Lint new Markdown files (enforced)
-        uses: DavidAnson/markdownlint-cli2-action@v23
-        if: steps.changed-markdown.outputs.has_added == 'true'
-        with:
-          globs: ${{ steps.changed-markdown.outputs.added_files }}
-
-      - name: Lint modified Markdown files (advisory)
-        uses: DavidAnson/markdownlint-cli2-action@v23
-        if: steps.changed-markdown.outputs.has_modified == 'true'
-        continue-on-error: true
+          {
+            echo 'files<<EOF'
+            git ls-files '*.md' '*.markdown'
+            echo 'EOF'
+          } >> "${GITHUB_OUTPUT}"
+      - name: Lint tracked Markdown files
+        uses: DavidAnson/markdownlint-cli2-action@v24
         with:
-          globs: ${{ steps.changed-markdown.outputs.modified_files }}
+          globs: ${{ steps.tracked-markdown.outputs.files }}

.github/workflows/test.yml

@@ -15,7 +15,7 @@ jobs:
     steps:
       # needs fetch-depth because the packaging dem reads old git tags
       - name: Checkout current PR
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
         with:
           fetch-depth: 0
       - name: Install Ruby version 3.3
@@ -36,7 +36,7 @@ jobs:
     steps:
       # needs fetch-depth because the packaging gem reads old git tags
       - name: Checkout current PR
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
         with:
           fetch-depth: 0
       - name: Install Ruby version 3.3
@@ -54,9 +54,7 @@ jobs:
       # into docs/ first, the same way the publish workflow does.
       - name: Generate reference docs
         run: |
-          bundle exec rake references:openfact INSTALLPATH=docs
-          bundle exec rake references:openvox INSTALLPATH=docs
-          bundle exec rake references:openbolt INSTALLPATH=docs
+          bundle exec rake references:all INSTALLPATH=docs
       - name: Build site
         run: bundle exec jekyll build
       - name: Check internal links

.markdownlint.yaml

@@ -1,8 +1,18 @@
 ---
 default: true
 
+# Line length is capped high (400), rather than at a typical prose width.
+# These docs are ported with one-paragraph-per-line source: a whole paragraph
+# is a single source line, which the renderer wraps to the viewport, so the
+# raw line length has no effect on the published page. Enforcing a tight limit
+# would mean reflowing ~800 lines purely for source formatting, with nothing
+# visible to readers. We keep a high cap anyway because very long source lines
+# do hurt diff review and editing -- 400 leaves normal long prose alone while
+# still flagging the genuinely unreadable outliers. Table rows can't wrap, so
+# they're exempt at any limit.
 line-length:
-  line_length: 210
+  line_length: 400
+  tables: false
 
 blank_lines:
   maximum: 2

CONTRIBUTING.md

@@ -51,6 +51,13 @@ bundle exec rake references:openfact INSTALLPATH=docs
 bundle exec rake references:openbolt INSTALLPATH=docs
 ```
 
+Or build every pinned product/version at once — this is what CI does, reading the
+pins from `_data/products.yml`:
+
+```console
+bundle exec rake references:all INSTALLPATH=docs
+```
+
 Note: It is possible to specify a version (tag or branch) to be used.
 If no version is provided, the latest stable release tag will be used.
 This is useful when checking for changes made in upstream reference source like OpenFact or OpenBolt repo itself.
@@ -61,6 +68,22 @@ bundle exec rake references:openfact INSTALLPATH=docs VERSION=main
 bundle exec rake references:openbolt INSTALLPATH=docs VERSION=main
 ```
 
+By default the references are built into each product's current stable collection
+(e.g. `_openvox_latest`). Use `COLLECTION` to target a specific version's directory,
+for example when regenerating a frozen older major from its matching upstream tag:
+
+```console
+bundle exec rake references:openvox INSTALLPATH=docs VERSION=8.27.0 COLLECTION=_openvox_8x
+```
+
+To build every pinned product/version in one go — the same way CI does — use
+`references:all`, which reads the version/tag pins from `_data/products.yml`
+(it does not take `VERSION` or `COLLECTION`):
+
+```console
+bundle exec rake references:all INSTALLPATH=docs
+```
+
 ## Writing guidelines
 
 ### Naming of OpenVox and Puppet

Gemfile

@@ -21,7 +21,7 @@ group(:generate_references) do
   gem 'pandoc-ruby'
   gem 'pragmatic_segmenter', '~> 0.3'
   gem 'punkt-segmenter', '~> 0.9'
-  gem 'rdoc', '~> 7.1'
+  gem 'rdoc', '~> 8.0'
   gem 'rgen', '~> 0.8'
   gem 'yard', '~> 0.9'
 end