Skip to content

Commit d4152df

Browse files
Jimbo4350Jimbo4350
committed
Merge master into release/cardano-api-11.0.0.0
Brings in PR #1180 (Haddock cross-package link fix) which landed on master after the release branch was cut. Docs-site only — no package code changes.
2 parents 0bb644a + e194f1a commit d4152df

3 files changed

Lines changed: 974 additions & 0 deletions

File tree

‎.changes/20260428_cardano_api_fix_haddock_links.yml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
project: cardano-api
2+
pr: 1180
3+
kind:
4+
- bugfix
5+
- documentation
6+
description: |
7+
Fix broken cross-package Haddock links on the hosted documentation site. Links to dependency packages (cardano-ledger-*, plutus-*, cardano-base, etc.) were relative paths pointing to directories that don't exist on the site, resulting in 404s. A post-processing script now resolves each cross-package href via a name-suffix heuristic under *.cardano.intersectmbo.org plus a small fallback list of known IOG doc-site roots, and rewrites them to absolute URLs. Hrefs that don't resolve become annotated unclickable spans with tooltips. A follow-up GitHub Actions step opens or comments on a rolling tracking issue when the script reports actionable dead links on master, tagging the PR opener so the breakage lands on someone's board instead of going unnoticed.

‎.github/workflows/github-page.yml‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,11 @@ jobs:
3939
mkdir website
4040
cabal haddock-project --output=./website --internal --foreign-libraries
4141
42+
- name: Fix cross-package Haddock links
43+
id: fix-haddock-links
44+
run: |
45+
./scripts/fix-haddock-links.sh ./website
46+
4247
- name: Build typedoc documentation
4348
run: |
4449
nix build .#wasm-typedoc
@@ -65,3 +70,177 @@ jobs:
6570
publish_dir: website
6671
cname: cardano-api.cardano.intersectmbo.org
6772
force_orphan: true
73+
74+
# ──────────────────────────────────────────────────────────────────
75+
# Tracking-issue logic for post-merge dead-link failures.
76+
#
77+
# Why: when fix-haddock-links.sh exits 1 on master (because some
78+
# newly-introduced CHaP package has no entry in IOG_DOC_BASES /
79+
# KNOWN_UNDOCUMENTED), the Deploy step further down skips and the
80+
# docs site stays at its last good revision. Without this step, the
81+
# only signal that something is broken is a red Actions run that
82+
# nobody is necessarily watching. This step opens a GitHub issue
83+
# tagging whoever introduced the breakage, so it lands on someone's
84+
# board instead of going unnoticed.
85+
#
86+
# Behaviour summary: one rolling issue per outage period. First
87+
# failure opens a new issue. Subsequent failures (while the issue
88+
# is still open) append a comment instead of opening a duplicate.
89+
# Once a maintainer fixes the root cause and closes the issue, the
90+
# next failure opens a fresh one.
91+
#
92+
# The fire conditions on the `if:` line below — all three required:
93+
# - failure() → the job overall is failing
94+
# - steps.fix-haddock-links.outcome → specifically the haddock-links
95+
# == 'failure' step failed (not e.g. cabal,
96+
# nix-shell, or the typedoc build)
97+
# - github.ref == 'refs/heads/master' → only on master pushes; not
98+
# on workflow_dispatch from
99+
# feature branches
100+
- name: Open / update dead-link tracking issue
101+
if: failure() && steps.fix-haddock-links.outcome == 'failure' && github.ref == 'refs/heads/master'
102+
uses: actions/github-script@v7
103+
with:
104+
script: |
105+
// Marker label used to identify the rolling tracking issue.
106+
// Looking up issues by label is more robust than by title (a
107+
// title match would break the moment someone edits the title).
108+
const labelName = 'haddock-ci-failure';
109+
const titleText = 'Haddock dead-link CI failures on master';
110+
111+
// ─── 1. Ensure the marker label exists ──────────────────────
112+
// First time this step ever fires, the label doesn't exist
113+
// yet and createLabel returns 201. Every subsequent run, the
114+
// API returns 422 ("name has already been taken") which we
115+
// swallow so the step continues. Any other error (403 = no
116+
// permission, 5xx = GitHub outage, etc.) re-throws and fails
117+
// the step, leaving a stack trace for debugging.
118+
try {
119+
await github.rest.issues.createLabel({
120+
owner: context.repo.owner,
121+
repo: context.repo.repo,
122+
name: labelName,
123+
color: 'd93f0b',
124+
description: 'Post-merge haddock-links CI failures (rolling tracking issue)',
125+
});
126+
} catch (e) {
127+
if (e.status !== 422) throw e;
128+
}
129+
130+
// ─── 2. Identify the breaker ────────────────────────────────
131+
// We want to @-mention the *PR opener* (the author who wrote
132+
// the change), not the merger (who clicked the merge button)
133+
// or the committer (whose name might be set to a bot identity).
134+
// listPullRequestsAssociatedWithCommit takes the new master
135+
// HEAD's SHA and returns the PR(s) that produced it. Works for
136+
// merge-commit, rebase, and squash-merge styles — GitHub
137+
// records the commit→PR association regardless. We read
138+
// pr.user.login from the result to get the PR opener.
139+
//
140+
// Fallback: in the unlikely case a master commit has no
141+
// associated PR (direct push by a maintainer), use
142+
// context.actor — the user who triggered the workflow run.
143+
const { data: prs } = await github.rest.repos.listPullRequestsAssociatedWithCommit({
144+
owner: context.repo.owner,
145+
repo: context.repo.repo,
146+
commit_sha: context.sha,
147+
});
148+
const pr = prs[0];
149+
const author = pr ? pr.user.login : context.actor;
150+
const prRef = pr ? `#${pr.number}` : `commit ${context.sha.slice(0, 7)}`;
151+
const runUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`;
152+
153+
// Body fragment used both as the comment body (when an issue
154+
// already exists) and appended to the issue body (when we
155+
// create a new one). Same content, two contexts.
156+
const commentBody = [
157+
`### New failure`,
158+
``,
159+
`On master after ${prRef} (committed by @${author}).`,
160+
``,
161+
`**Run:** ${runUrl}`,
162+
``,
163+
`Open the run log and look for \`=== Actionable — fix these ===\` to see which package(s) the probe couldn't resolve.`,
164+
].join('\n');
165+
166+
// ─── 3. Look up the existing tracking issue ─────────────────
167+
// Filter by `state: open` so a closed (i.e. already-fixed)
168+
// tracking issue doesn't get reused — we want a fresh issue
169+
// for the next outage period, not to reopen a stale one.
170+
// per_page: 1 because we only need to know whether ANY exists.
171+
const { data: issues } = await github.rest.issues.listForRepo({
172+
owner: context.repo.owner,
173+
repo: context.repo.repo,
174+
state: 'open',
175+
labels: labelName,
176+
per_page: 1,
177+
});
178+
179+
// ─── 4. Branch on whether one was found ─────────────────────
180+
if (issues.length > 0) {
181+
// Existing open issue → comment on it; don't open a duplicate.
182+
// Also add the new breaker as an assignee (idempotent — if
183+
// they're already assigned the API silently no-ops).
184+
const existing = issues[0];
185+
await github.rest.issues.createComment({
186+
owner: context.repo.owner,
187+
repo: context.repo.repo,
188+
issue_number: existing.number,
189+
body: commentBody,
190+
});
191+
try {
192+
await github.rest.issues.addAssignees({
193+
owner: context.repo.owner,
194+
repo: context.repo.repo,
195+
issue_number: existing.number,
196+
assignees: [author],
197+
});
198+
} catch (e) {
199+
// External contributors aren't repo collaborators, so the API
200+
// returns 422 here. Log and continue rather than crashing the
201+
// step — the comment was posted, which is the important part.
202+
console.log(`Could not assign @${author} to #${existing.number} (likely not a repo collaborator): ${e.message}`);
203+
}
204+
console.log(`Appended to existing issue #${existing.number}: ${existing.html_url}`);
205+
} else {
206+
// No open issue → create one. The body documents the fix
207+
// recipe so the assignee doesn't need to find it elsewhere.
208+
const issueBody = [
209+
`Tracking issue for post-merge \`Update github pages\` workflow failures on the haddock-links check. The Deploy step skips on failure, so the published docs site stays at its last good revision until this issue is resolved.`,
210+
``,
211+
`## How to fix`,
212+
``,
213+
`For each package listed under \`=== Actionable — fix these ===\` in the failing run:`,
214+
``,
215+
`1. Check the package's source repo for a published Haddocks site (gh-pages, CloudFront, etc.).`,
216+
`2. If found: append the base URL to \`IOG_DOC_BASES\` in \`scripts/fix-haddock-links.sh\`.`,
217+
`3. If genuinely unpublished: add the package name to \`KNOWN_UNDOCUMENTED\`.`,
218+
``,
219+
`Then re-run the workflow from the Actions tab. Close this issue once the workflow goes green again.`,
220+
``,
221+
`---`,
222+
``,
223+
commentBody,
224+
].join('\n');
225+
// Create the issue without assignees first — passing assignees
226+
// to issues.create makes the whole call 422 for non-collaborator
227+
// authors. We assign separately so the issue always lands.
228+
const created = await github.rest.issues.create({
229+
owner: context.repo.owner,
230+
repo: context.repo.repo,
231+
title: titleText,
232+
body: issueBody,
233+
labels: [labelName],
234+
});
235+
try {
236+
await github.rest.issues.addAssignees({
237+
owner: context.repo.owner,
238+
repo: context.repo.repo,
239+
issue_number: created.data.number,
240+
assignees: [author],
241+
});
242+
} catch (e) {
243+
console.log(`Could not assign @${author} to #${created.data.number} (likely not a repo collaborator): ${e.message}`);
244+
}
245+
console.log(`Opened tracking issue #${created.data.number}: ${created.data.html_url}`);
246+
}

0 commit comments

Comments
 (0)