Skip to content

ci(links): exclude dynamic review comment anchors #2197

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
josecelano merged 6 commits into from
Sep 11, 2026
+218 −12
Merged

ci(links): exclude dynamic review comment anchors #2197

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
266c3bb
docs(links): classify external-link check baseline
josecelano Sep 9, 2026
0d135c5
docs(links): correct external-link baseline classification
josecelano Sep 10, 2026
50d4c47
ci(links): exclude dynamic review comment anchors
josecelano Sep 10, 2026
fcbb4bf
docs(review): audit PR 2197 Copilot suggestions
josecelano Sep 10, 2026
80334f7
docs(links): clarify review anchor verification
josecelano Sep 11, 2026
3c59070
docs(review): use completed audit tense
josecelano Sep 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .github/lychee-online.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,10 @@ include_fragments = "full"
# Avoid immutable historical issue records with known stale relative links.
exclude_path = [ "(^|/)docs/issues/closed/" ]

# GitHub renders pull-request review-comment anchors dynamically, so Lychee cannot
# reliably validate them. Keep all other GitHub URLs and fragments checked.
exclude = [ "^https://github\\.com/torrust/torrust-tracker/pull/[0-9]+#discussion_r[0-9]+$" ]

# Bound requests to respect external services while retaining actionable failures.
timeout = 20
max_retries = 2
Expand Down
54 changes: 54 additions & 0 deletions docs/copilot-pr-reviews/pr-2197-copilot-suggestions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
---
semantic-links:
skill-links:
- process-copilot-suggestions
related-artifacts:
- .github/skills/dev/pr-reviews/process-copilot-suggestions/SKILL.md
- docs/issues/open/2185-2003-triage-advisory-external-link-check-findings/ISSUE.md
- docs/issues/open/2185-2003-triage-advisory-external-link-check-findings/external-link-baseline.md
---

<!-- cspell:disable -->

<!-- skill-link: process-copilot-suggestions -->

# PR #2197 Copilot Suggestions Tracking

Source: Copilot PR review threads for <https://github.com/torrust/torrust-tracker/pull/2197>

Status legend:

- `action`: code/docs change applied
- `no-action`: suggestion reviewed; no code change needed
- `resolved`: thread resolved in PR

## Workflow

1. Download all review threads (including resolved/outdated state and thread IDs).
2. Add one row per thread in the Suggestions table.
3. Process suggestions one by one:
- decide `action` or `no-action`
- if `action`, apply change and validate
- if needed, commit changes
- reply on the PR thread with the fix commit and outcome, or the no-action rationale
- resolve the PR thread
4. Set `Thread State` to `resolved` once resolved in PR.

## Processing Log

- 2026-09-10: Started processing two Copilot suggestions.
- 2026-09-10: Confirmed the baseline table has no double-leading delimiters, replied to [thread 1](https://github.com/torrust/torrust-tracker/pull/2197#discussion_r3980472597), and resolved it as outdated.
- 2026-09-10: Confirmed the issue-spec tables have no double-leading delimiters, replied to [thread 2](https://github.com/torrust/torrust-tracker/pull/2197#discussion_r3980497474), and resolved it as outdated.
- 2026-09-10: Refreshed the review-thread list; no unresolved threads remained.

## Suggestions

| # | Thread ID | Path | URL | Suggestion Summary | Decision | Reply URL | Status | Thread State |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 1 | `PRRT_kwDOGp2yqc6hH6I2` | `docs/issues/open/2185-2003-triage-advisory-external-link-check-findings/external-link-baseline.md` | <https://github.com/torrust/torrust-tracker/pull/2197#discussion_r3980379439> | Remove the extra leading table delimiter. | `no-action`: confirmed obsolete; current rows use one leading delimiter. | <https://github.com/torrust/torrust-tracker/pull/2197#discussion_r3980472597> | DONE | RESOLVED |
| 2 | `PRRT_kwDOGp2yqc6hH6J1` | `docs/issues/open/2185-2003-triage-advisory-external-link-check-findings/ISSUE.md` | <https://github.com/torrust/torrust-tracker/pull/2197#discussion_r3980379539> | Remove the extra leading table delimiter. | `no-action`: confirmed obsolete; current rows use one leading delimiter. | <https://github.com/torrust/torrust-tracker/pull/2197#discussion_r3980497474> | DONE | RESOLVED |

## Notes

- Both threads are outdated after the baseline-document correction; direct inspection found no `||` table rows in either file.
- A visible reply was posted before resolving each thread.
28 changes: 16 additions & 12 deletions docs/issues/open/2185-2003-triage-advisory-external-link-check-findings/ISSUE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,14 +8,15 @@ github-issue: 2185
spec-path: docs/issues/open/2185-2003-triage-advisory-external-link-check-findings/ISSUE.md
branch: "2185-2003-triage-advisory-external-link-check-findings"
related-pr: null
last-updated-utc: 2026-09-09 12:10
last-updated-utc: 2026-09-10 07:25
semantic-links:
skill-links:
- create-issue
related-artifacts:
- .github/skills/dev/planning/create-issue/SKILL.md
- docs/issues/open/2003-overhaul-guardrails-and-automation/EPIC.md
- docs/issues/open/2162-enforce-lychee-and-schedule-external-link-checks/ISSUE.md
- docs/issues/open/2185-2003-triage-advisory-external-link-check-findings/external-link-baseline.md
- .github/workflows/external-link-check.yaml
- .github/lychee-online.toml
---
Expand Down Expand Up @@ -82,13 +83,13 @@ Not applicable. This is evidence-driven documentation maintenance and configurat

Status values: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`.

| ID | Status | Task | Notes / Expected Output |
| --- | ------ | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| T1 | TODO | Preserve and classify the baseline | Issue-local Markdown evidence maps each distinct URL or recurring pattern to a category and disposition. |
| T2 | TODO | Repair clearly stale references | Small, reviewable repairs replace or remove only references confirmed stale, with replacement-target evidence. |
| T3 | TODO | Add justified narrow exclusions | Online-only exclusions cover only confirmed, durable non-actionable categories and state their rationale. |
| T4 | TODO | Revalidate hosted signal | A manually dispatched run after each remediation slice demonstrates the expected change without hiding remaining failures. |
| T5 | TODO | Document operations and review completion | Triage procedure, residual risks, acceptance evidence, and independent review are updated from observed results. |
| ID | Status | Task | Notes / Expected Output |
| --- | ----------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| T1 | DONE | Preserve and classify the baseline | `external-link-baseline.md` maps all 461 report errors to nine recurring categories and dispositions. |
| T2 | TODO | Repair clearly stale references | Small, reviewable repairs replace or remove only references confirmed stale, with replacement-target evidence. |
| T3 | IN_PROGRESS | Add justified narrow exclusions | Added the exact C1/C9 pull-request review-comment-anchor candidate; hosted boundary verification is pending. |
| T4 | TODO | Revalidate hosted signal | A manually dispatched run after each remediation slice demonstrates the expected change without hiding remaining failures. |
| T5 | TODO | Document operations and review completion | Triage procedure, residual risks, acceptance evidence, and independent review are updated from observed results. |
Comment thread
josecelano marked this conversation as resolved.

## Commit Points

Expand All @@ -109,7 +110,7 @@ A category that needs no repository change is recorded in issue-local evidence w
- [x] Spec reviewed and approved by user/maintainer
- [x] GitHub issue created and issue number added to this spec
- [ ] (Optional, recommended for complex issues) Spec-only PR merged into `develop` before implementation
- [ ] Baseline classification reviewed
- [x] Baseline classification independently reviewed
- [ ] Implementation completed
- [ ] Automatic verification completed (`linter all`, relevant tests, and any pre-push checks)
- [ ] Manual verification scenarios executed and recorded (status + evidence)
Expand All @@ -124,10 +125,13 @@ A category that needs no repository change is recorded in issue-local evidence w

- 2026-09-09 12:00 UTC - Copilot - Drafted a proposed EPIC #2003 subissue from External Link Check [run 34347690674](https://github.com/torrust/torrust-tracker/actions/runs/34347690674), which scanned merged `develop` revision `7abc30b2` and retained a report with 461 errors for classification before any remediation.
- 2026-09-09 12:10 UTC - GitHub Operator - Created [issue #2185](https://github.com/torrust/torrust-tracker/issues/2185) with the `task` label and linked it as a subissue of [EPIC #2003](https://github.com/torrust/torrust-tracker/issues/2003) after maintainer approval.
- 2026-09-09 15:15 UTC - Copilot - Downloaded the retained report from [run 34347690674](https://github.com/torrust/torrust-tracker/actions/runs/34347690674), classified all 461 errors in `external-link-baseline.md`, and selected only GitHub pull-request review-comment anchors as the first proposed remediation slice. No production configuration or link was changed.
- 2026-09-10 07:09 UTC - Task Reviewer - Independently re-parsed the retained report and passed the corrected classification: $416+7+14+3+1+5+3+4+8=461$, with C1/C9 covering 424 exact GitHub pull-request review-comment-anchor failures. No broad exclusion is proposed; no configuration or link changed in this evidence-only slice.
- 2026-09-10 07:25 UTC - Copilot - Added the exact C1/C9 URL-pattern exclusion to `.github/lychee-online.toml`. A two-link Lychee boundary test excluded a pull-request review-comment anchor while retaining a GitHub issue-comment anchor as a visible error. Hosted rerun evidence remains pending.

## Acceptance Criteria

- [ ] AC1: An issue-local baseline records the exact hosted run, revision, summary counts, and a disposition for every distinct failing URL or recurring failure pattern.
- [x] AC1: An issue-local baseline records the exact hosted run, revision, summary counts, and a disposition for every distinct failing URL or recurring failure pattern.
- [ ] AC2: Each repair changes only a verified stale reference and records why its replacement target is correct.
- [ ] AC3: Each added exclusion is online-only, narrowly scoped to a documented durable false-positive category, and does not suppress unrelated external-link failures.
- [ ] AC4: The advisory workflow remains scheduled/manual, visibly fails for remaining external-link failures, and continues to upload its Markdown report on failure.
Expand Down Expand Up @@ -155,7 +159,7 @@ Status values: `TODO`, `IN_PROGRESS`, `DONE`, `FAILED`, `BLOCKED`.
| ID | Scenario | Command/Steps | Expected Result | Status | Evidence |
| --- | ------------------------------ | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| M1 | Reproduce baseline | Manually dispatch `external-link-check.yaml` on `develop`; download `lychee-external-link-report`. | Report is available even when Lychee fails; baseline counts and categories can be reviewed. | DONE | [Run 34347690674](https://github.com/torrust/torrust-tracker/actions/runs/34347690674), revision `7abc30b2`, 461 errors, 0 timeouts. |
| M2 | Classify durable failures | Review all report entries and group by URL/pattern, response type, owning document, and proposed disposition. | Every baseline failure has a traceable disposition; no broad host-level suppression is proposed. | TODO | Issue-local classification artifact. |
| M2 | Classify durable failures | Review all report entries and group by URL/pattern, response type, owning document, and proposed disposition. | Every baseline failure has a traceable disposition; no broad host-level suppression is proposed. | DONE | `external-link-baseline.md`; independent reconciliation passed on 2026-09-10. |
| M3 | Verify reference repairs | Check each changed target using the appropriate authoritative source, then run local validation. | Replacement reference is correct and offline local-link validation remains clean. | TODO | Focused commands and review evidence. |
| M4 | Verify exclusion boundaries | Dispatch the hosted workflow after adding a proposed exclusion. | The intended durable false-positive category is absent, while representative unrelated external failures remain visible and the report uploads. | TODO | Hosted run URL and artifact summary. |
| M5 | Distinguish transient failures | Re-run a newly observed timeout, 403, or other potentially transient result once. | The record distinguishes a persistent failure from a transient response before an exclusion or repair decision. | TODO | Pair of hosted-run URLs and comparison. |
Expand All @@ -164,7 +168,7 @@ Status values: `TODO`, `IN_PROGRESS`, `DONE`, `FAILED`, `BLOCKED`.

| AC ID | Status (`TODO`/`DONE`) | Evidence |
| ----- | ---------------------- | ----------------------------------------------------------------- |
| AC1 | TODO | Issue-local baseline and classification table. |
| AC1 | DONE | `external-link-baseline.md` from run 34347690674. |
| AC2 | TODO | Reviewed reference-repair commits and target evidence. |
| AC3 | TODO | Configuration diff and hosted rerun showing exclusion boundaries. |
| AC4 | TODO | Workflow source and hosted failure/report artifact. |
Expand Down
Loading
Loading