From b3729e58f744501ed08a10dd1dfd4693fa875441 Mon Sep 17 00:00:00 2001 From: Kristin Martin Date: Wed, 21 Oct 2026 17:50:00 +0000 Subject: [PATCH 1/7] Debug the Vale CI run Temporary: adds debug: true to the vale-action step so the job log shows how Vale resolves .vale.ini and StylesPath in CI. Vale has returned {} on every run since the glob fix in #2544 while finding issues locally, tracked in docs-tracking#375. Also fixes one 'utilize' on litefs/how-it-works so a prose file with a known remaining finding is in the diff for Vale to be handed. --- .github/workflows/vale-docs-linter.yml | 1 + litefs/how-it-works.mdx | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/vale-docs-linter.yml b/.github/workflows/vale-docs-linter.yml index 43404c4cf6..98d125ebb6 100644 --- a/.github/workflows/vale-docs-linter.yml +++ b/.github/workflows/vale-docs-linter.yml @@ -23,6 +23,7 @@ jobs: - name: run reviewdog and linter uses: errata-ai/vale-action@reviewdog with: + debug: true files: ${{ steps.changed-files.outputs.all_changed_and_modified_files }} separator: "," # added, diff_context, file, nofilter diff --git a/litefs/how-it-works.mdx b/litefs/how-it-works.mdx index b95df6a419..2de40ac544 100644 --- a/litefs/how-it-works.mdx +++ b/litefs/how-it-works.mdx @@ -85,7 +85,7 @@ rolling checksum. ## Cluster management using leases SQLite operates as a single-writer database which means only one transaction can -write at a time. Because of this, we utilize a lease system whereby a single +write at a time. Because of this, we use a lease system whereby a single node acts as the "primary" node at any given time. All writes should be directed to that node and it will propagate changes to the rest of the cluster. From 6b20c799fef6ee2826a2b63cf5b794a556f7fefe Mon Sep 17 00:00:00 2001 From: Kristin Martin Date: Wed, 21 Oct 2026 17:51:22 +0000 Subject: [PATCH 2/7] Probe Vale's config resolution in CI Temporary. The action's debug flag only logs its own inputs, so this runs vale sync, ls-config and a direct lint in a plain step to see StylesPath, the matched sections and the loaded styles as CI sees them. --- .github/workflows/vale-docs-linter.yml | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/.github/workflows/vale-docs-linter.yml b/.github/workflows/vale-docs-linter.yml index 98d125ebb6..767057125a 100644 --- a/.github/workflows/vale-docs-linter.yml +++ b/.github/workflows/vale-docs-linter.yml @@ -19,6 +19,18 @@ jobs: with: fetch_depth: 2 + # TEMPORARY probe for docs-tracking#375 + - name: probe vale directly + run: | + curl -sL https://github.com/errata-ai/vale/releases/download/v3.24.0/vale_3.24.0_Linux_64-bit.tar.gz -o /tmp/vale.tgz + mkdir -p /tmp/valebin && tar xzf /tmp/vale.tgz -C /tmp/valebin + echo "--- pwd and tree ---"; pwd; ls -la .vale.ini; ls styles/ || true + echo "--- vale sync ---"; /tmp/valebin/vale sync 2>&1 | tail -2 + echo "--- styles after sync ---"; ls styles/; ls styles/Fly 2>&1 | head -3 + echo "--- ls-config ---"; /tmp/valebin/vale ls-config 2>&1 | head -40 + echo "--- direct run ---"; /tmp/valebin/vale --no-exit --output=line litefs/how-it-works.mdx 2>&1 | head -5 + echo "--- exit marker ---" + # run reviewdog and the linter - name: run reviewdog and linter uses: errata-ai/vale-action@reviewdog From ab38fed5efae11e5774165d6263a847c4dcd5af5 Mon Sep 17 00:00:00 2001 From: Kristin Martin Date: Wed, 21 Oct 2026 17:53:10 +0000 Subject: [PATCH 3/7] Extend the probe: run the action's exact args, and dump VALE env vars --- .github/workflows/vale-docs-linter.yml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.github/workflows/vale-docs-linter.yml b/.github/workflows/vale-docs-linter.yml index 767057125a..b90bb3fbff 100644 --- a/.github/workflows/vale-docs-linter.yml +++ b/.github/workflows/vale-docs-linter.yml @@ -28,7 +28,10 @@ jobs: echo "--- vale sync ---"; /tmp/valebin/vale sync 2>&1 | tail -2 echo "--- styles after sync ---"; ls styles/; ls styles/Fly 2>&1 | head -3 echo "--- ls-config ---"; /tmp/valebin/vale ls-config 2>&1 | head -40 - echo "--- direct run ---"; /tmp/valebin/vale --no-exit --output=line litefs/how-it-works.mdx 2>&1 | head -5 + echo "--- direct run, line ---"; /tmp/valebin/vale --no-exit --output=line litefs/how-it-works.mdx 2>&1 | head -5 + echo "--- action's exact args, our binary ---"; /tmp/valebin/vale --output=JSON .github/workflows/vale-docs-linter.yml litefs/how-it-works.mdx 2>&1 | head -c 300; echo + echo "--- hosted binary, if present ---"; ls /opt/hostedtoolcache/vale/*/x64/vale 2>/dev/null || echo "(not yet installed)" + echo "--- env that could affect vale ---"; env | grep -iE "^VALE|STYLES" || echo "(none)" echo "--- exit marker ---" # run reviewdog and the linter From 219533dc4b314b7e6879bedcb3a74afabb30bad2 Mon Sep 17 00:00:00 2001 From: Kristin Martin Date: Wed, 21 Oct 2026 17:54:31 +0000 Subject: [PATCH 4/7] Probe the action's own vale binary after it runs Same args and cwd give findings with a binary from errata-ai releases and {} with the one the action installs, so compare the two directly: version, the Fly checks each loads, and a direct lint. --- .github/workflows/vale-docs-linter.yml | 28 ++++++++++++-------------- 1 file changed, 13 insertions(+), 15 deletions(-) diff --git a/.github/workflows/vale-docs-linter.yml b/.github/workflows/vale-docs-linter.yml index b90bb3fbff..daacd6bf60 100644 --- a/.github/workflows/vale-docs-linter.yml +++ b/.github/workflows/vale-docs-linter.yml @@ -19,21 +19,6 @@ jobs: with: fetch_depth: 2 - # TEMPORARY probe for docs-tracking#375 - - name: probe vale directly - run: | - curl -sL https://github.com/errata-ai/vale/releases/download/v3.24.0/vale_3.24.0_Linux_64-bit.tar.gz -o /tmp/vale.tgz - mkdir -p /tmp/valebin && tar xzf /tmp/vale.tgz -C /tmp/valebin - echo "--- pwd and tree ---"; pwd; ls -la .vale.ini; ls styles/ || true - echo "--- vale sync ---"; /tmp/valebin/vale sync 2>&1 | tail -2 - echo "--- styles after sync ---"; ls styles/; ls styles/Fly 2>&1 | head -3 - echo "--- ls-config ---"; /tmp/valebin/vale ls-config 2>&1 | head -40 - echo "--- direct run, line ---"; /tmp/valebin/vale --no-exit --output=line litefs/how-it-works.mdx 2>&1 | head -5 - echo "--- action's exact args, our binary ---"; /tmp/valebin/vale --output=JSON .github/workflows/vale-docs-linter.yml litefs/how-it-works.mdx 2>&1 | head -c 300; echo - echo "--- hosted binary, if present ---"; ls /opt/hostedtoolcache/vale/*/x64/vale 2>/dev/null || echo "(not yet installed)" - echo "--- env that could affect vale ---"; env | grep -iE "^VALE|STYLES" || echo "(none)" - echo "--- exit marker ---" - # run reviewdog and the linter - name: run reviewdog and linter uses: errata-ai/vale-action@reviewdog @@ -50,3 +35,16 @@ jobs: # Required, set by GitHub actions automatically: # https://docs.github.com/en/actions/security-guides/automatic-token-authentication#about-the-github_token-secret GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}} + + # TEMPORARY probe for docs-tracking#375: compare the action's binary + - name: probe the action's own vale binary + if: always() + run: | + HOSTED=$(ls /opt/hostedtoolcache/vale/*/x64/vale | head -1) + echo "--- hosted binary ---"; echo "$HOSTED"; $HOSTED --version + echo "--- hosted: checks loaded ---"; $HOSTED ls-config 2>&1 | python3 -c "import json,sys; d=json.load(sys.stdin); print([c for c in d['Checks'] if c.startswith('Fly.')])" || true + echo "--- hosted: direct run ---"; $HOSTED --no-exit --output=line litefs/how-it-works.mdx 2>&1 | head -3 + echo "--- mine for comparison ---"; /tmp/valebin/vale --version 2>/dev/null || curl -sL https://github.com/errata-ai/vale/releases/download/v3.24.0/vale_3.24.0_Linux_64-bit.tar.gz -o /tmp/v.tgz && mkdir -p /tmp/valebin && tar xzf /tmp/v.tgz -C /tmp/valebin && /tmp/valebin/vale --version + echo "--- mine: checks loaded ---"; /tmp/valebin/vale ls-config 2>&1 | python3 -c "import json,sys; d=json.load(sys.stdin); print([c for c in d['Checks'] if c.startswith('Fly.')])" || true + echo "--- sizes ---"; ls -l "$HOSTED" /tmp/valebin/vale + echo "--- exit marker ---" From 71dc18d32f288d1f35fcd9bedee91fd001f19351 Mon Sep 17 00:00:00 2001 From: Kristin Martin Date: Wed, 21 Oct 2026 17:55:28 +0000 Subject: [PATCH 5/7] Test whether a wrong cwd explains the empty result --- .github/workflows/vale-docs-linter.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/workflows/vale-docs-linter.yml b/.github/workflows/vale-docs-linter.yml index daacd6bf60..9230ba31bd 100644 --- a/.github/workflows/vale-docs-linter.yml +++ b/.github/workflows/vale-docs-linter.yml @@ -47,4 +47,8 @@ jobs: echo "--- mine for comparison ---"; /tmp/valebin/vale --version 2>/dev/null || curl -sL https://github.com/errata-ai/vale/releases/download/v3.24.0/vale_3.24.0_Linux_64-bit.tar.gz -o /tmp/v.tgz && mkdir -p /tmp/valebin && tar xzf /tmp/v.tgz -C /tmp/valebin && /tmp/valebin/vale --version echo "--- mine: checks loaded ---"; /tmp/valebin/vale ls-config 2>&1 | python3 -c "import json,sys; d=json.load(sys.stdin); print([c for c in d['Checks'] if c.startswith('Fly.')])" || true echo "--- sizes ---"; ls -l "$HOSTED" /tmp/valebin/vale + echo "--- cwd hypothesis: run from /tmp with relative paths ---" + (cd /tmp && $HOSTED --output=JSON litefs/how-it-works.mdx 2>&1 | head -c 120); echo + echo "--- and with absolute paths from /tmp ---" + (cd /tmp && $HOSTED --output=JSON "$GITHUB_WORKSPACE/litefs/how-it-works.mdx" 2>&1 | head -c 120); echo echo "--- exit marker ---" From 0193494fa84fc483446fcc80fe2a879edd61b955 Mon Sep 17 00:00:00 2001 From: Kristin Martin Date: Wed, 21 Oct 2026 17:57:16 +0000 Subject: [PATCH 6/7] Fix the separator so Vale is passed a file list it can read tj-actions/changed-files emits a space-separated list, and the step told vale-action the list was comma-separated. The action split on a comma that was not there, so Vale received a single argument holding every path joined by spaces. Vale answers an unmatched path with an empty result and exit 0, so the check has reported nothing at all. Reproduced both ways with the same binary and config: vale --output=JSON 'a.yml b.mdx' -> {} vale --output=JSON a.yml b.mdx -> the findings in b.mdx This predates the Mintlify migration, so the glob fix in #2544 was correct and this was masking it. docs-tracking#375. Keeps one 'utilize' fix on litefs/how-it-works so a prose file with a remaining finding is in the diff and CI has something to report. --- .github/workflows/vale-docs-linter.yml | 24 +++++------------------- 1 file changed, 5 insertions(+), 19 deletions(-) diff --git a/.github/workflows/vale-docs-linter.yml b/.github/workflows/vale-docs-linter.yml index 9230ba31bd..ef8a798738 100644 --- a/.github/workflows/vale-docs-linter.yml +++ b/.github/workflows/vale-docs-linter.yml @@ -23,9 +23,12 @@ jobs: - name: run reviewdog and linter uses: errata-ai/vale-action@reviewdog with: - debug: true + # tj-actions/changed-files emits a space-separated list. Telling the + # action it is comma-separated made it pass Vale one argument holding + # every path, which Vale answers with an empty result and exit 0, so + # this check reported nothing at all. See docs-tracking#375. files: ${{ steps.changed-files.outputs.all_changed_and_modified_files }} - separator: "," + separator: " " # added, diff_context, file, nofilter filter_mode: file # github-pr-check, github-pr-review, github-check @@ -35,20 +38,3 @@ jobs: # Required, set by GitHub actions automatically: # https://docs.github.com/en/actions/security-guides/automatic-token-authentication#about-the-github_token-secret GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}} - - # TEMPORARY probe for docs-tracking#375: compare the action's binary - - name: probe the action's own vale binary - if: always() - run: | - HOSTED=$(ls /opt/hostedtoolcache/vale/*/x64/vale | head -1) - echo "--- hosted binary ---"; echo "$HOSTED"; $HOSTED --version - echo "--- hosted: checks loaded ---"; $HOSTED ls-config 2>&1 | python3 -c "import json,sys; d=json.load(sys.stdin); print([c for c in d['Checks'] if c.startswith('Fly.')])" || true - echo "--- hosted: direct run ---"; $HOSTED --no-exit --output=line litefs/how-it-works.mdx 2>&1 | head -3 - echo "--- mine for comparison ---"; /tmp/valebin/vale --version 2>/dev/null || curl -sL https://github.com/errata-ai/vale/releases/download/v3.24.0/vale_3.24.0_Linux_64-bit.tar.gz -o /tmp/v.tgz && mkdir -p /tmp/valebin && tar xzf /tmp/v.tgz -C /tmp/valebin && /tmp/valebin/vale --version - echo "--- mine: checks loaded ---"; /tmp/valebin/vale ls-config 2>&1 | python3 -c "import json,sys; d=json.load(sys.stdin); print([c for c in d['Checks'] if c.startswith('Fly.')])" || true - echo "--- sizes ---"; ls -l "$HOSTED" /tmp/valebin/vale - echo "--- cwd hypothesis: run from /tmp with relative paths ---" - (cd /tmp && $HOSTED --output=JSON litefs/how-it-works.mdx 2>&1 | head -c 120); echo - echo "--- and with absolute paths from /tmp ---" - (cd /tmp && $HOSTED --output=JSON "$GITHUB_WORKSPACE/litefs/how-it-works.mdx" 2>&1 | head -c 120); echo - echo "--- exit marker ---" From 763aaf6d45cc746249ed7d084d0834d569116222 Mon Sep 17 00:00:00 2001 From: Kristin Martin Date: Wed, 21 Oct 2026 18:06:45 +0000 Subject: [PATCH 7/7] Correct the comment: it skipped multi-file PRs, not every PR Kristin remembered Vale flagging things before the migration, which is right. A one-file PR joins to a single valid path, so the check worked on those from 2023 and silently skipped anything larger. Kaelyn's #2217 last September is an example: one file changed, and Vale reported on it. --- .github/workflows/vale-docs-linter.yml | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/.github/workflows/vale-docs-linter.yml b/.github/workflows/vale-docs-linter.yml index ef8a798738..ea36c75d34 100644 --- a/.github/workflows/vale-docs-linter.yml +++ b/.github/workflows/vale-docs-linter.yml @@ -23,10 +23,13 @@ jobs: - name: run reviewdog and linter uses: errata-ai/vale-action@reviewdog with: - # tj-actions/changed-files emits a space-separated list. Telling the + # tj-actions/changed-files emits a space-separated list, so telling the # action it is comma-separated made it pass Vale one argument holding - # every path, which Vale answers with an empty result and exit 0, so - # this check reported nothing at all. See docs-tracking#375. + # every path joined by spaces. That is a valid path only when a PR + # changed exactly one file, so from 2023 this check worked on + # single-file PRs and silently skipped every larger one: Vale answers + # an unmatched path with an empty result and exit 0. See + # docs-tracking#375. files: ${{ steps.changed-files.outputs.all_changed_and_modified_files }} separator: " " # added, diff_context, file, nofilter