Skip to content

Commit 30941a2

Browse files
rwgkrwgk
committed
Merge branch 'main' into rwgk/contributor-review-coordination
2 parents a7c2f6f + b288fc8 commit 30941a2

33 files changed

Lines changed: 1572 additions & 677 deletions

‎.github/actions/check-doc-links/action.yml‎

Lines changed: 0 additions & 114 deletions
This file was deleted.

‎.github/actions/lychee-links/action.yml‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2+
#
3+
# SPDX-License-Identifier: Apache-2.0
4+
5+
name: Check documentation links
6+
description: Run a configured Lychee pre-commit hook with the shared URL cache and retained reports
7+
8+
inputs:
9+
kind:
10+
description: "Which hook to run: authored or rendered"
11+
required: true
12+
policy:
13+
description: >-
14+
check accepts up to 10 rate-limited URLs; cache-warm warns for any unresolved
15+
link; allow-429 accepts only HTTP 429 failures under the maintainer override
16+
default: check
17+
refresh:
18+
description: "Check links afresh and publish the successful results as the new baseline"
19+
default: "false"
20+
pr-number:
21+
description: "PR whose current maintainer override label should be read; empty skips the lookup"
22+
default: ""
23+
24+
outputs:
25+
allow-429:
26+
description: "Whether the current PR label explicitly enables the HTTP 429 override"
27+
value: ${{ steps.lychee-policy.outputs.allow-429 }}
28+
29+
# Callers provide Python and the checked-out repository; the build of any
30+
# rendered documentation must already be complete.
31+
runs:
32+
using: composite
33+
steps:
34+
- name: Read the PR's Lychee rate-limit override
35+
id: lychee-policy
36+
shell: bash --noprofile --norc -euo pipefail {0}
37+
env:
38+
GH_TOKEN: ${{ github.token }}
39+
GH_REPO: ${{ github.repository }}
40+
PR_NUMBER: ${{ inputs.pr-number }}
41+
run: |
42+
allow_429=false
43+
if [[ -n "$PR_NUMBER" ]]; then
44+
# Reruns keep the original event's labels, so query the current decision.
45+
# Only an exact boolean response can enable the maintainer override.
46+
lookup_ok=false
47+
for attempt in 1 2 3; do
48+
if result="$(gh pr view "$PR_NUMBER" --json labels --jq '.labels | any(.name == "ci: lychee-non-blocking")')"; then
49+
case "$result" in
50+
true|false) allow_429="$result"; lookup_ok=true; break ;;
51+
esac
52+
fi
53+
if (( attempt < 3 )); then
54+
sleep $((attempt * 5))
55+
fi
56+
done
57+
if [[ "$lookup_ok" != true ]]; then
58+
echo "::warning::Could not read a valid PR label decision; using the default link policy. Rerun to apply ci: lychee-non-blocking."
59+
elif [[ "$allow_429" == true ]]; then
60+
echo "::notice::ci: lychee-non-blocking permits only HTTP 429 failures after retries."
61+
fi
62+
fi
63+
echo "allow-429=$allow_429" >> "$GITHUB_OUTPUT"
64+
65+
- name: Describe the link cache
66+
id: cache
67+
shell: bash --noprofile --norc -euo pipefail {0}
68+
env:
69+
KIND: ${{ inputs.kind }}
70+
# Anything that can change a check result or the cache's meaning. The
71+
# hook configuration carries the native wheel pin and every hook option.
72+
POLICY_HASH: ${{ hashFiles('.pre-commit-config.yaml', 'lychee.toml', 'ci/tools/run_lychee.py', 'ci/tools/run_lychee_precommit.py', 'ci/tools/retry_lychee.py', 'ci/tools/checkout_source_links.py') }}
73+
run: |
74+
# Authored and rendered results stay apart: only rendered checks validate
75+
# fragments, and Lychee's cache does not record which validation ran.
76+
case "${KIND}" in
77+
authored) path=.lycheecache ;;
78+
rendered) path=.lychee-rendered/.lycheecache ;;
79+
*) echo "::error::Unknown link-check kind: ${KIND}"; exit 1 ;;
80+
esac
81+
prefix="lychee-v1-${KIND}-${POLICY_HASH}-baseline-"
82+
echo "path=${path}" >> "${GITHUB_OUTPUT}"
83+
echo "prefix=${prefix}" >> "${GITHUB_OUTPUT}"
84+
echo "key=${prefix}${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}" >> "${GITHUB_OUTPUT}"
85+
86+
- name: Restore successful link checks
87+
id: cache-restore
88+
# Refresh mode deliberately skips earlier URL results.
89+
if: ${{ inputs.refresh != 'true' }}
90+
uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
91+
with:
92+
path: ${{ steps.cache.outputs.path }}
93+
key: ${{ steps.cache.outputs.key }}
94+
restore-keys: ${{ steps.cache.outputs.prefix }}
95+
enableCrossOsArchive: true
96+
97+
- name: Explain a missing shared Lychee cache
98+
# Prefix restores are normal; cache-hit only identifies exact key matches.
99+
if: ${{ inputs.refresh != 'true' && steps.cache-restore.outputs.cache-matched-key == '' }}
100+
shell: bash --noprofile --norc -euo pipefail {0}
101+
env:
102+
KIND: ${{ inputs.kind }}
103+
DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
104+
WORKFLOW_URL: ${{ github.server_url }}/${{ github.repository }}/actions/workflows/lychee.yml
105+
run: |
106+
message="No shared Lychee ${KIND} cache was restored for this checker configuration. Checking links without this baseline may take longer and make more network requests."
107+
context="This is expected after checker changes in a PR; a refresh on ${DEFAULT_BRANCH} cannot seed settings that exist only in a PR."
108+
hint="For an unexpected miss on ${DEFAULT_BRANCH}, maintainers can run CI: Lychee checks and caches (lychee.yml) on ${DEFAULT_BRANCH} with refresh-cache enabled."
109+
echo "::notice title=Lychee ${KIND} cache::${message} ${context} ${hint} ${WORKFLOW_URL}"
110+
{
111+
printf '### Lychee %s cache\n\n' "$KIND"
112+
printf '%s\n\n%s\n\n%s\n\n' "$message" "$context" "$hint"
113+
printf '[Open the cache refresh workflow](%s).\n' "$WORKFLOW_URL"
114+
} >> "$GITHUB_STEP_SUMMARY"
115+
116+
- name: Check links through the configured pre-commit hook
117+
shell: bash --noprofile --norc -euo pipefail {0}
118+
env:
119+
KIND: ${{ inputs.kind }}
120+
POLICY: ${{ steps.lychee-policy.outputs.allow-429 == 'true' && 'allow-429' || inputs.policy }}
121+
GITHUB_TOKEN: ${{ github.token }}
122+
run: |
123+
# Install into the interpreter that runs the driver, whatever shell
124+
# profile the caller's other steps use.
125+
python -m pip install pre-commit
126+
python ci/tools/run_lychee_precommit.py "${KIND}" --policy "${POLICY}" --max-attempts 3 \
127+
--report "${RUNNER_TEMP}/lychee-reports/lychee-${KIND}.json"
128+
129+
- name: Publish fresh successful link checks
130+
# Only refresh runs publish, so every pull request restores the same
131+
# baseline. Saving keeps original timestamps and never caches failures.
132+
if: ${{ !cancelled() && inputs.refresh == 'true' }}
133+
uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
134+
with:
135+
path: ${{ steps.cache.outputs.path }}
136+
key: ${{ steps.cache.outputs.key }}
137+
enableCrossOsArchive: true
138+
139+
- name: Upload link-check reports
140+
if: ${{ always() }}
141+
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
142+
with:
143+
name: lychee-${{ inputs.kind }}-${{ runner.os }}-${{ github.run_id }}-${{ github.run_attempt }}
144+
path: ${{ runner.temp }}/lychee-reports/
145+
if-no-files-found: ignore
146+
retention-days: 7

‎.github/dependabot.yml‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -36,10 +36,6 @@ updates:
3636
# Match hook repositories, leaving additional_dependencies pins unchanged.
3737
allow:
3838
- dependency-name: "https://github.com/*"
39-
# Lychee's hook revision, LYCHEE_VERSION argument, and CI binary pin must
40-
# be upgraded together in a coordinated manual update.
41-
ignore:
42-
- dependency-name: "https://github.com/lycheeverse/lychee"
4339

4440
groups:
4541
pre-commit-monthly:

‎.github/workflows/build-docs.yml‎

Lines changed: 13 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -118,7 +118,7 @@ jobs:
118118
fi
119119
else
120120
FILE_HASH="${{ github.sha }}"
121-
DOCS_GITHUB_REF="${{ github.sha }}"
121+
DOCS_GITHUB_REF=$(python ci/tools/checkout_source_links.py --github-ref)
122122
fi
123123
124124
# make outputs from the previous job as env vars
@@ -284,21 +284,25 @@ jobs:
284284
fi
285285
mv ${COMPONENT}/docs/build/html/* artifacts/docs/${TARGET}
286286
287-
# Keep link checks in the existing PR docs build, using the same revision
288-
# as its wheels. Nightly supplies shared caches for both kinds of inputs.
289-
- name: Check authored documentation links
287+
# Check links and anchors in the rendered HTML built above.
288+
# Links in authored Markdown and reST files are checked separately by the
289+
# ordinary Linux/Windows pre-commit jobs.
290+
# The link-check action runs in a non-login shell, so give it a known
291+
# interpreter instead of the conda environment used above.
292+
- name: Set up Python for link checks
290293
if: ${{ !inputs.is-release && startsWith(github.ref_name, 'pull-request/') }}
291-
timeout-minutes: 60
292-
uses: ./.github/actions/check-doc-links
294+
uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
293295
with:
294-
kind: authored
296+
python-version: "3.14"
295297

296-
- name: Check rendered documentation links
298+
- name: Check rendered documentation links through pre-commit
297299
if: ${{ !inputs.is-release && startsWith(github.ref_name, 'pull-request/') }}
298300
timeout-minutes: 60
299-
uses: ./.github/actions/check-doc-links
301+
uses: ./.github/actions/lychee-links
300302
with:
301303
kind: rendered
304+
# Full CI's pull-request/N mirror supplies the PR number.
305+
pr-number: ${{ env.PR_NUMBER }}
302306

303307
- name: Upload docs GitHub Pages artifact
304308
if: ${{ inputs.deploy-docs }}

‎.github/workflows/lychee.yml‎

Lines changed: 25 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,12 @@
22
#
33
# SPDX-License-Identifier: Apache-2.0
44

5-
# Build documentation nightly and warm the link cache, reporting unresolved links
6-
# as warnings. Full PR CI reuses successful checks in build-docs.yml.
7-
# Ordinary PR updates run pre-commit without Lychee and do not build docs here.
5+
# Warm authored and rendered link caches through the configured pre-commit
6+
# hooks. Ordinary PRs reuse authored results; full docs CI reuses rendered
7+
# results. Nightly and manual dispatches with refresh-cache=true start afresh,
8+
# report unresolved links as warnings, and can produce both shared baselines.
89

9-
name: "CI: Documentation links"
10+
name: "CI: Lychee checks and caches"
1011

1112
on:
1213
workflow_call:
@@ -50,6 +51,10 @@ jobs:
5051
fail-fast: false
5152
matrix:
5253
kind: [authored, rendered]
54+
env:
55+
PYTHONUTF8: "1"
56+
# Reuse the same minor version for Python setup and cache fallback.
57+
PYTHON_VERSION: "3.14"
5358
steps:
5459
- name: Checkout checked revision
5560
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -62,9 +67,20 @@ jobs:
6267
submodules: ${{ matrix.kind == 'rendered' }}
6368

6469
- name: Set up Python
70+
id: python
6571
uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
6672
with:
67-
python-version: "3.14"
73+
python-version: ${{ env.PYTHON_VERSION }}
74+
75+
- name: Set pre-commit cache location
76+
run: echo "PRE_COMMIT_HOME=${RUNNER_TEMP}/pre-commit" >> "${GITHUB_ENV}"
77+
78+
- name: Restore pre-commit environments
79+
uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
80+
with:
81+
path: ${{ env.PRE_COMMIT_HOME }}
82+
key: pre-commit-${{ runner.os }}-py${{ steps.python.outputs.python-version }}-${{ hashFiles('.pre-commit-config.yaml') }}
83+
restore-keys: pre-commit-${{ runner.os }}-py${{ env.PYTHON_VERSION }}
6884

6985
- name: Setup pixi
7086
if: ${{ matrix.kind == 'rendered' }}
@@ -74,9 +90,9 @@ jobs:
7490
if: ${{ matrix.kind == 'rendered' }}
7591
run: pixi run --manifest-path cuda_core/pixi.toml -e docs docs-build-all-latest
7692

77-
- name: Check documentation links
78-
uses: ./.github/actions/check-doc-links
93+
- name: Check documentation links through pre-commit
94+
uses: ./.github/actions/lychee-links
7995
with:
8096
kind: ${{ matrix.kind }}
81-
refresh-cache: ${{ inputs.refresh-cache || false }}
82-
failure-policy: ${{ inputs.refresh-cache && 'cache-warm' || 'check' }}
97+
policy: ${{ inputs.refresh-cache && 'cache-warm' || 'check' }}
98+
refresh: ${{ inputs.refresh-cache || false }}

0 commit comments

Comments
 (0)