Adding link checker script + GitHub CI #886
Conversation
|
Warning Rate limit exceeded@aireilly has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 7 minutes and 51 seconds before requesting another review. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📒 Files selected for processing (4)
WalkthroughThis change introduces automated link-checking for AsciiDoc documentation files. It adds a GitHub Actions workflow and supporting Bash scripts to check for broken links in modified Changes
Sequence Diagram(s)sequenceDiagram
participant GitHub
participant Workflow
participant check-modified.sh
participant check-links.sh
GitHub->>Workflow: Push or Pull Request event
Workflow->>check-modified.sh: Run to detect modified .adoc files
check-modified.sh->>check-links.sh: For each updated book, run link check
check-links.sh->>External URLs: Validate each URL (parallel curl)
check-links.sh-->>check-modified.sh: Report broken links (if any)
check-modified.sh-->>Workflow: Exit with status (success/failure)
Workflow-->>GitHub: Post check result
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~15 minutes ✨ Finishing Touches
🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
Documentation and Community
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (6)
scripts/check-links.sh (4)
15-21: Argument parsing blocks legitimate use-casesThe script only accepts either the
--globalflag or exactly one file argument.
It becomes impossible to check several specific files at once, or to pass additional flags (for example a future--verbose). This limitation will quickly surface in CI when multiple.adocfiles change in the same commit outsideassemblies/.-elif [ "$#" -eq 1 ]; then - INPUT_FILE="$1" +elif [ "$#" -ge 1 ]; then + INPUT_FILE=("$@") # allow an arbitrary list
28-37: Ignore list is hard-wired & will driftAll patterns are baked into the script; updating them requires committing code instead of tweaking CI variables.
Consider letting callers extend / override the list via an environment variable, e.g.LINKCHECK_IGNORE_REGEX, and splitting on|. That keeps the script generic and reusable across repos.
45-47: Only the last trailing punctuation character is stripped
${URL%[.,;:?!\]\)]}removes one character.
Strings such ashttps://foo.com).will be truncated tohttps://foo.com)and still fail.-URL=${URL%[.,;:?!\]\)]} +while [[ "$URL" =~ [.,;:?!\]\)]$ ]]; do + URL=${URL%?} +done
83-86: Temporary file never cleaned up
mktempcreates a real file that stays in/tmp.
Trap EXIT to delete it:+trap 'rm -f "$TMP_FILE"' EXIT.github/workflows/check-links.yml (2)
8-19: Global job lacks cache & matrix – runtime will growRunning the checker over all assemblies on every PR can take several minutes as the doc set grows.
Consider:
- Caching Asciidoctor’s gem downloads (
actions/cache)- Using a matrix to shard the file list and run checks in parallel
40-41: Pattern excludes moved or renamed filesThe regex
^assemblies/[^/]+\.adoc$skips files moved to sub-directories or renamed within nested paths.
If that was unintentional, drop the anchor or use**/*.adoc.
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
.github/workflows/check-links.yml(1 hunks)scripts/check-links.sh(1 hunks)
🧰 Additional context used
🧠 Learnings (2)
📓 Common learnings
Learnt from: bredamc
PR: opendatahub-io/opendatahub-documentation#860
File: modules/using-llm-as-a-judge-metrics-with-lmeval.adoc:62-65
Timestamp: 2025-07-16T09:05:50.422Z
Learning: In the opendatahub-documentation project, bredamc prefers comprehensive error detection in code reviews. Continue to point out potential errors whether they are related to the code changes in the PR or not, but clearly distinguish between errors introduced in the PR versus errors in existing code.
Learnt from: bredamc
PR: opendatahub-io/opendatahub-documentation#842
File: modules/enabling-the-multi-model-serving-platform.adoc:11-17
Timestamp: 2025-07-07T19:36:45.326Z
Learning: In the opendatahub-documentation project, AsciiDoc anchors like `ref-dashboard-configuration-options_dashboard` are automatically generated when module files are included in assembly files, rather than being manually defined with [[anchor]] syntax. Links to these anchors will not 404 because the anchor is created through the inclusion mechanism.
scripts/check-links.sh (1)
Learnt from: bredamc
PR: #842
File: modules/enabling-the-multi-model-serving-platform.adoc:11-17
Timestamp: 2025-07-07T19:36:45.326Z
Learning: In the opendatahub-documentation project, AsciiDoc anchors like ref-dashboard-configuration-options_dashboard are automatically generated when module files are included in assembly files, rather than being manually defined with [[anchor]] syntax. Links to these anchors will not 404 because the anchor is created through the inclusion mechanism.
🔇 Additional comments (2)
scripts/check-links.sh (1)
70-71: Regex misses many valid URLs
[a-zA-Z0-9./?=%_-]*excludes&,#,:,~, etc.
Consider using a more permissive pattern or lettingpandoc/asciidoctoremit links in XML/JSON and parse that..github/workflows/check-links.yml (1)
36-45:origin/${{ github.base_ref }}may not exist in shallow clonesEven with
fetch-depth: 0, the remote ref is namedrefs/remotes/origin/<branch>.
Inside containers, Git sometimes flattens remotes ⇒ the diff can be empty and the job silently passes.A more robust variant:
BASE=${{ github.event.pull_request.base.sha }} git diff --name-only $BASE...HEAD
scripts/check-links.sh
Outdated
| # Export variables and functions for xargs subshells | ||
| export TMP_FILE | ||
| export -f check_url | ||
|
|
||
| run_url_checks() { | ||
| local FILE="$1" | ||
| echo -e "\033[32mChecking: $FILE\033[0m" | ||
| asciidoctor "$FILE" -o - | \ | ||
| grep -Eo '(http|https)://[a-zA-Z0-9./?=%_-]*' | \ | ||
| sort -u | \ | ||
| xargs -P 10 -n 1 bash -c "$PATTERNS_DECL; check_url \"\$0\"" | ||
| } |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Race-condition & brittle $0 usage inside xargs
- Multiple parallel subshells write to the same
TMP_FILE, which can interleave.
Writing1once is fine, but concurrent writes could still truncate the file at the wrong moment. - Using
$0to pass the URL relies on Bash’s special handling ofarg0and is hard to read.
xargs -I{}is clearer.
- xargs -P 10 -n 1 bash -c "$PATTERNS_DECL; check_url \"\$0\""
+ xargs -P 10 -n 1 -I{} bash -c "$PATTERNS_DECL; check_url \"{}\""You can also switch to mktemp -u + touch and replace echo >| with printf >> to eliminate the truncation race.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| # Export variables and functions for xargs subshells | |
| export TMP_FILE | |
| export -f check_url | |
| run_url_checks() { | |
| local FILE="$1" | |
| echo -e "\033[32mChecking: $FILE\033[0m" | |
| asciidoctor "$FILE" -o - | \ | |
| grep -Eo '(http|https)://[a-zA-Z0-9./?=%_-]*' | \ | |
| sort -u | \ | |
| xargs -P 10 -n 1 bash -c "$PATTERNS_DECL; check_url \"\$0\"" | |
| } | |
| # Export variables and functions for xargs subshells | |
| export TMP_FILE | |
| export -f check_url | |
| run_url_checks() { | |
| local FILE="$1" | |
| echo -e "\033[32mChecking: $FILE\033[0m" | |
| asciidoctor "$FILE" -o - | \ | |
| grep -Eo '(http|https)://[a-zA-Z0-9./?=%_-]*' | \ | |
| sort -u | \ | |
| xargs -P 10 -n 1 -I{} bash -c "$PATTERNS_DECL; check_url \"{}\"" | |
| } |
🤖 Prompt for AI Agents
In scripts/check-links.sh around lines 62 to 73, fix the race condition caused
by multiple parallel subshells writing to the same TMP_FILE by switching to a
unique temporary file per process using mktemp -u combined with touch, and
replace echo >| with printf >> to avoid truncation issues. Also, replace the use
of $0 in the xargs bash -c call with xargs -I{} to pass the URL argument more
clearly and reliably.
scripts/check-links.sh
Outdated
| if [ "$GLOBAL_MODE" -eq 1 ]; then | ||
| while IFS= read -r file; do | ||
| run_url_checks "$file" | ||
| done < <(find assemblies -maxdepth 1 -type f -name "*.adoc") | ||
| else |
There was a problem hiding this comment.
find … -maxdepth 1 ignores sub-assemblies
assemblies already contains nested directories (e.g. ai/), so deeper .adoc files are skipped in global mode.
Dropping -maxdepth 1 fixes it:
- done < <(find assemblies -maxdepth 1 -type f -name "*.adoc")
+ done < <(find assemblies -type f -name "*.adoc")🤖 Prompt for AI Agents
In scripts/check-links.sh around lines 75 to 79, the find command uses -maxdepth
1 which limits the search to only the top-level files in the assemblies
directory, ignoring nested subdirectories and their .adoc files. To fix this,
remove the -maxdepth 1 option from the find command so it recursively finds all
.adoc files in assemblies and its subdirectories when GLOBAL_MODE is 1.
aireilly
force-pushed
the
add-link-checker
branch
from
0766a32 to
95cc918
Compare
aireilly
force-pushed
the
add-link-checker
branch
16 times, most recently
from
abb49f9 to
5ee707f
Compare
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (2)
scripts/check-links.sh (2)
70-72: Past feedback still unaddressed –$0in xargs & racePrior review pointed out that relying on
$0insidebash -cis brittle and thatxargscan pass the argument explicitly. The issue remains.- xargs -P 10 -n 1 bash -c "$PATTERNS_DECL; check_url \"\$0\"" + xargs -P 10 -n 1 -I{} bash -c "$PATTERNS_DECL; check_url \"{}\""This also sidesteps
$0quirks and makes the call self-documenting.
25-29: Single shared temp file +echo >is racy under parallel curlParallel subshells write to the same
TMP_FILE; simultaneous truncation (>redirection) can clobber the flag and hide failures.-echo "0" > "$TMP_FILE" +printf '0' >"$TMP_FILE"And inside
check_url(Line 58)- echo "1" > "$TMP_FILE" + printf '1' >>"$TMP_FILE"For complete safety allocate one file per process (
mktemp --tmpdir check_links.XXXXXX) and test existence rather than contents.
🧹 Nitpick comments (2)
.github/workflows/check-links.yml (1)
13-17: Apt installs on every run – consider pre-built Asciidoctor action
apt-get update && apt-get installadds ~30 s to every CI run. Switching to the maintainedasciidoctor/docker-actionor a pre-built container cuts that to near-zero and avoids future package-availability failures.scripts/check-links.sh (1)
3-4: Header comment is now misleadingThe script no longer “Checks for 404 links” only. It validates all non-2xx/3xx statuses (except 000/403). Please update the comment to avoid confusion.
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
.github/workflows/check-links.yml(1 hunks)scripts/check-links.sh(1 hunks)scripts/links.ignore(1 hunks)
✅ Files skipped from review due to trivial changes (1)
- scripts/links.ignore
🧰 Additional context used
🧠 Learnings (2)
📓 Common learnings
Learnt from: bredamc
PR: opendatahub-io/opendatahub-documentation#860
File: modules/using-llm-as-a-judge-metrics-with-lmeval.adoc:62-65
Timestamp: 2025-07-16T09:05:50.422Z
Learning: In the opendatahub-documentation project, bredamc prefers comprehensive error detection in code reviews. Continue to point out potential errors whether they are related to the code changes in the PR or not, but clearly distinguish between errors introduced in the PR versus errors in existing code.
📚 Learning: in asciidoc assembly files, the conditional directive syntax `ifdef::parent-context[:context: {paren...
Learnt from: jiridanek
PR: opendatahub-io/opendatahub-documentation#801
File: assemblies/managing-basic-workbenches.adoc:30-31
Timestamp: 2025-06-17T10:51:51.206Z
Learning: In AsciiDoc assembly files, the conditional directive syntax `ifdef::parent-context[:context: {parent-context}]` and `ifndef::parent-context[:!context:]` is valid and commonly used for managing document context when files are included in different assemblies. This pattern should not be flagged as malformed syntax.
Applied to files:
scripts/check-links.sh
🔇 Additional comments (1)
scripts/check-links.sh (1)
54-57: Why are 403 & 000 silently accepted?Treating all non-2xx/3xx statuses as broken is safer; many sites respond with 403 when public access is blocked (broken link for readers). Please document the rationale or remove the exception.
-if [[ "$STATUS" != "000" && "$STATUS" != "403" && ! "$STATUS" =~ ^(2|3)[0-9]{2}$ ]]; then +if [[ ! "$STATUS" =~ ^(2|3)[0-9]{2}$ ]]; then
.github/workflows/check-links.yml
Outdated
| MODIFIED_FILES=$(git diff --name-only origin/main...HEAD --diff-filter=d -- "*.adoc") | ||
| CHECK_FILES=() | ||
|
|
||
| while IFS= read -r file; do | ||
| [[ "$file" =~ ^assemblies/[^/]+\.adoc$ ]] && CHECK_FILES+=("$file") | ||
| done <<< "$MODIFIED_FILES" | ||
|
|
There was a problem hiding this comment.
💡 Verification agent
❓ Verification inconclusive
Regex rejects nested assemblies – link-check silently skips many changed files
The path filter ^assemblies/[^/]+\.adoc$ matches only files that are directly inside assemblies/ (one level). All .adoc files already living in deeper sub-directories (assemblies/ai/…, assemblies/model_serving/…, etc.) will never be checked even when modified, defeating the purpose of this workflow.
- [[ "$file" =~ ^assemblies/[^/]+\.adoc$ ]] && CHECK_FILES+=("$file")
+ [[ "$file" =~ ^assemblies/.*\.adoc$ ]] && CHECK_FILES+=("$file")Run the workflow on a branch that touches assemblies/ai/example.adoc to confirm the fix.
Include nested assembly .adoc files in link-check workflow
The current regex only matches .adoc files directly under assemblies/, so any documents in subfolders (e.g. assemblies/ai/example.adoc) are never checked. Update the pattern to capture all .adoc files under assemblies/.
• File: .github/workflows/check-links.yml
Lines ~27–33 (regex filter)
• Change:
- [[ "$file" =~ ^assemblies/[^/]+\.adoc$ ]] && CHECK_FILES+=("$file")
+ [[ "$file" =~ ^assemblies/.*\.adoc$ ]] && CHECK_FILES+=("$file")📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| MODIFIED_FILES=$(git diff --name-only origin/main...HEAD --diff-filter=d -- "*.adoc") | |
| CHECK_FILES=() | |
| while IFS= read -r file; do | |
| [[ "$file" =~ ^assemblies/[^/]+\.adoc$ ]] && CHECK_FILES+=("$file") | |
| done <<< "$MODIFIED_FILES" | |
| MODIFIED_FILES=$(git diff --name-only origin/main...HEAD --diff-filter=d -- "*.adoc") | |
| CHECK_FILES=() | |
| while IFS= read -r file; do | |
| - [[ "$file" =~ ^assemblies/[^/]+\.adoc$ ]] && CHECK_FILES+=("$file") | |
| + [[ "$file" =~ ^assemblies/.*\.adoc$ ]] && CHECK_FILES+=("$file") | |
| done <<< "$MODIFIED_FILES" |
🤖 Prompt for AI Agents
In .github/workflows/check-links.yml around lines 27 to 33, the regex only
matches .adoc files directly under assemblies/ and misses nested files in
subfolders. Update the regex pattern to match all .adoc files under assemblies/,
including those in any subdirectories, by allowing for additional path segments
after assemblies/ before the filename.
scripts/check-links.sh
Outdated
| # Strip trailing punctuation | ||
| URL=${URL%[.,;:?!\]\)]} | ||
|
|
There was a problem hiding this comment.
Bad glob ‑- script aborts with “bad pattern” on Bash 5.1
${URL%[.,;:?!\]\)]} closes the bracket set at the first ], making the back-slash sequence invalid. Bash exits with bad pattern the first time a URL is processed.
- URL=${URL%[.,;:?!\]\)]}
+ # Trim a single trailing punctuation char if present
+ URL=${URL%%[[:punct:]]}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| # Strip trailing punctuation | |
| URL=${URL%[.,;:?!\]\)]} | |
| # Trim a single trailing punctuation char if present | |
| URL=${URL%%[[:punct:]]} |
🤖 Prompt for AI Agents
In scripts/check-links.sh around lines 45 to 47, the pattern used to strip
trailing punctuation from the URL is invalid because the closing bracket is
interpreted too early, causing a "bad pattern" error in Bash 5.1. To fix this,
escape the closing square bracket inside the bracket expression properly or
reorder the characters so that the closing bracket is not the first character
after the opening bracket, ensuring the glob pattern is valid and does not cause
the script to abort.
77015ea to
95f7e2b
Compare
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (2)
.github/workflows/check-links.yml (1)
20-24: Minor: avoidchmodwhen scripts are tracked as executable
check-links.shandcheck-modified.shalready have the shebang and can be committed with the executable bit (git add --chmod=+x).
Dropping this step reduces noise.[nitpick]
scripts/check-modified.sh (1)
44-47: Deduplicate list to avoid redundant link checksWhen a module appears in multiple books, the current loop checks each book repeatedly.
-# Check links in the compiled list of books -for f in "${UPDATED_BOOKS[@]}"; do - ./scripts/check-links.sh "$f" -done +# Check links once per unique book +for f in $(printf '%s\n' "${UPDATED_BOOKS[@]}" | sort -u); do + ./scripts/check-links.sh "$f" +done
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (6)
.github/workflows/check-links.yml(1 hunks)assemblies/upgrading-odh-v2.adoc(1 hunks)customizing-models-with-lab-tuning.adoc(1 hunks)scripts/check-links.sh(1 hunks)scripts/check-modified.sh(1 hunks)scripts/links.ignore(1 hunks)
✅ Files skipped from review due to trivial changes (1)
- customizing-models-with-lab-tuning.adoc
🚧 Files skipped from review as they are similar to previous changes (2)
- scripts/links.ignore
- scripts/check-links.sh
🧰 Additional context used
🧠 Learnings (7)
📓 Common learnings
Learnt from: bredamc
PR: opendatahub-io/opendatahub-documentation#860
File: modules/using-llm-as-a-judge-metrics-with-lmeval.adoc:62-65
Timestamp: 2025-07-16T09:05:50.422Z
Learning: In the opendatahub-documentation project, bredamc prefers comprehensive error detection in code reviews. Continue to point out potential errors whether they are related to the code changes in the PR or not, but clearly distinguish between errors introduced in the PR versus errors in existing code.
Learnt from: bredamc
PR: opendatahub-io/opendatahub-documentation#842
File: modules/enabling-the-multi-model-serving-platform.adoc:11-17
Timestamp: 2025-07-07T19:36:45.326Z
Learning: In the opendatahub-documentation project, AsciiDoc anchors like `ref-dashboard-configuration-options_dashboard` are automatically generated when module files are included in assembly files, rather than being manually defined with [[anchor]] syntax. Links to these anchors will not 404 because the anchor is created through the inclusion mechanism.
📚 Learning: in asciidoc assembly files, the conditional directive syntax `ifdef::parent-context[:context: {paren...
Learnt from: jiridanek
PR: opendatahub-io/opendatahub-documentation#801
File: assemblies/managing-basic-workbenches.adoc:30-31
Timestamp: 2025-06-17T10:51:51.206Z
Learning: In AsciiDoc assembly files, the conditional directive syntax `ifdef::parent-context[:context: {parent-context}]` and `ifndef::parent-context[:!context:]` is valid and commonly used for managing document context when files are included in different assemblies. This pattern should not be flagged as malformed syntax.
Applied to files:
.github/workflows/check-links.ymlassemblies/upgrading-odh-v2.adoc
📚 Learning: in the opendatahub-documentation project, asciidoc anchors like `ref-dashboard-configuration-options...
Learnt from: bredamc
PR: opendatahub-io/opendatahub-documentation#842
File: modules/enabling-the-multi-model-serving-platform.adoc:11-17
Timestamp: 2025-07-07T19:36:45.326Z
Learning: In the opendatahub-documentation project, AsciiDoc anchors like `ref-dashboard-configuration-options_dashboard` are automatically generated when module files are included in assembly files, rather than being manually defined with [[anchor]] syntax. Links to these anchors will not 404 because the anchor is created through the inclusion mechanism.
Applied to files:
assemblies/upgrading-odh-v2.adocscripts/check-modified.sh
📚 Learning: in asciidoc files for opendatahub-documentation, when adding explanatory text after list items, avoi...
Learnt from: bredamc
PR: opendatahub-io/opendatahub-documentation#816
File: modules/deploying-models-on-the-single-model-serving-platform.adoc:0-0
Timestamp: 2025-06-16T11:11:20.681Z
Learning: In AsciiDoc files for opendatahub-documentation, when adding explanatory text after list items, avoid using block continuation markers ('+') if the text should appear in the same paragraph as the list item. The block continuation marker would move the text to a new paragraph within the same step, which may not be the desired rendering.
Applied to files:
assemblies/upgrading-odh-v2.adoc
📚 Learning: in the opendatahub-documentation project, avoid suggesting unnecessary admonition blocks (note, warn...
Learnt from: bredamc
PR: opendatahub-io/opendatahub-documentation#860
File: modules/using-llm-as-a-judge-metrics-with-lmeval.adoc:62-65
Timestamp: 2025-07-16T09:10:15.185Z
Learning: In the opendatahub-documentation project, avoid suggesting unnecessary admonition blocks (NOTE, WARNING, IMPORTANT, etc.) for explanatory text that can be effectively communicated inline. The documentation team prefers cleaner, less cluttered documentation with inline text unless the information is critical enough to warrant special formatting emphasis.
Applied to files:
assemblies/upgrading-odh-v2.adoc
📚 Learning: in asciidoc documentation for opendatahub-documentation, when adding explanatory text after a list i...
Learnt from: bredamc
PR: opendatahub-io/opendatahub-documentation#816
File: modules/deploying-models-on-the-single-model-serving-platform.adoc:0-0
Timestamp: 2025-06-16T11:11:27.675Z
Learning: In AsciiDoc documentation for opendatahub-documentation, when adding explanatory text after a list item, the preferred rendering is to keep the text in the same paragraph as the list item (no `+` continuation character) rather than creating a separate paragraph within the same step using the `+` block continuation character.
Applied to files:
assemblies/upgrading-odh-v2.adoc
📚 Learning: in the opendatahub-documentation repository, some lines using asciidoc comment syntax (`//`) are del...
Learnt from: bredamc
PR: opendatahub-io/opendatahub-documentation#816
File: modules/deploying-teacher-and-judge-models.adoc:0-0
Timestamp: 2025-06-16T11:06:25.386Z
Learning: In the opendatahub-documentation repository, some lines using AsciiDoc comment syntax (`//`) are deliberately commented out and should not be converted to visible NOTE blocks or other visible content. The author intentionally keeps certain guidance as non-rendered comments.
Applied to files:
assemblies/upgrading-odh-v2.adoc
| - name: Fetch base branch | ||
| run: git fetch origin main | ||
|
|
There was a problem hiding this comment.
🛠️ Refactor suggestion
Fetching origin/main breaks on PRs from forks – use base repo ref instead
For PRs raised from a fork, origin points to the fork, not the upstream repo, so git fetch origin main often fails or fetches an outdated branch.
Use the base-ref provided by GitHub Actions or add an explicit upstream remote.
- - name: Fetch base branch
- run: git fetch origin main
+ - name: Fetch base branch
+ if: ${{ github.event_name == 'pull_request' }}
+ run: |
+ git fetch \
+ "https://github.com/${{ github.repository_owner }}/opendatahub-documentation.git" \
+ "${{ github.event.pull_request.base.ref }}:refs/remotes/upstream/${{ github.event.pull_request.base.ref }}"📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - name: Fetch base branch | |
| run: git fetch origin main | |
| - name: Fetch base branch | |
| if: ${{ github.event_name == 'pull_request' }} | |
| run: | | |
| git fetch \ | |
| "https://github.com/${{ github.repository_owner }}/opendatahub-documentation.git" \ | |
| "${{ github.event.pull_request.base.ref }}:refs/remotes/upstream/${{ github.event.pull_request.base.ref }}" |
🤖 Prompt for AI Agents
In .github/workflows/check-links.yml around lines 25 to 27, the command 'git
fetch origin main' fails on PRs from forks because 'origin' points to the fork
repository. To fix this, replace 'origin' with the upstream repository reference
or use the GitHub Actions base-ref variable to fetch the correct base branch
from the upstream repo. Alternatively, add an explicit remote for the upstream
repo and fetch from it instead of 'origin'.
assemblies/upgrading-odh-v2.adoc
Outdated
|
|
||
| https://docs.redhat.com/derp |
There was a problem hiding this comment.
💡 Verification agent
❓ Verification inconclusive
Placeholder URL will fail link-check and confuses readers
https://docs.redhat.com/derp looks like a stub/typo.
It renders as a naked paragraph with no context and will inevitably 404, causing the very link-checker introduced in this PR to fail.
-ifndef::parent-context[:!context:]
-
-https://docs.redhat.com/derp
+ifndef::parent-context[:!context:]
+
+// TODO: replace with the correct RH docs link once available.
+// For now, comment it out to avoid CI failures.
+// https://docs.redhat.com/<correct-path>Replace the placeholder docs URL to prevent CI link-check failures
The stub URL https://docs.redhat.com/derp will always 404 and break our new link-checker. Please remove or comment it out until the correct Red Hat documentation path is known.
• Location: assemblies/upgrading-odh-v2.adoc, lines 28–30
• Action: replace the naked link with a TODO comment (or remove it) to keep the build green
Suggested diff:
-ifndef::parent-context[:!context:]
-
-https://docs.redhat.com/derp
+ifndef::parent-context[:!context:]
+
+// TODO: insert the correct Red Hat docs URL here once available.
// For now, comment out the stub to avoid CI failures.
// https://docs.redhat.com/<correct-path>🤖 Prompt for AI Agents
In assemblies/upgrading-odh-v2.adoc around lines 28 to 30, the placeholder URL
https://docs.redhat.com/derp causes CI link-check failures because it 404s.
Remove this URL or replace it with a TODO comment indicating the correct Red Hat
documentation path is pending, to prevent build breaks.
scripts/check-modified.sh
Outdated
| #!/bin/bash | ||
| # | ||
| # Checks for 404 links in modified books | ||
|
|
There was a problem hiding this comment.
🛠️ Refactor suggestion
Harden script: fail fast & safer globbing
Add standard Bash safety switches (set -Eeuo pipefail) and IFS to avoid subtle bugs when filenames contain spaces.
-#!/bin/bash
+#!/usr/bin/env bash
+set -Eeuo pipefail
+IFS=$'\n\t'🤖 Prompt for AI Agents
In scripts/check-modified.sh at lines 1 to 4, the script lacks safety measures
for robust execution. Add the Bash safety options by including `set -Eeuo
pipefail` near the top of the script to enable fail-fast behavior and better
error handling. Also, set `IFS` to a safe value like newline and tab to handle
filenames with spaces correctly and prevent globbing issues.
| # | ||
| # Checks for 404 links in modified books | ||
|
|
||
| FILES=$(git diff --name-only origin/main...HEAD --diff-filter=d -- "*.adoc") |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Diff against wrong remote on forked PRs
git diff origin/main...HEAD has the same fork issue as the workflow.
Derive the base branch dynamically:
-FILES=$(git diff --name-only origin/main...HEAD --diff-filter=d -- "*.adoc")
+BASE=${GITHUB_BASE_REF:-main}
+FILES=$(git diff --name-only "origin/${BASE}"...HEAD --diff-filter=d -- "*.adoc")📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| FILES=$(git diff --name-only origin/main...HEAD --diff-filter=d -- "*.adoc") | |
| BASE=${GITHUB_BASE_REF:-main} | |
| FILES=$(git diff --name-only "origin/${BASE}"...HEAD --diff-filter=d -- "*.adoc") |
🤖 Prompt for AI Agents
In scripts/check-modified.sh at line 5, the git diff command uses a hardcoded
remote branch origin/main which causes issues on forked PRs. Modify the script
to dynamically determine the base branch or remote reference instead of using
origin/main directly. This can be done by deriving the base branch from the
current git context or environment variables to ensure the diff compares against
the correct upstream branch in forked PR scenarios.
3cef4f1 to
e612b25
Compare
aireilly
force-pushed
the
add-link-checker
branch
from
e612b25 to
007019d
Compare
Description
Adding link checker script + GitHub CI yml
Example CI failure: https://github.com/aireilly/opendatahub-documentation/actions/runs/16655212911/job/47138351717
Summary by CodeRabbit