0xMiden / 0xMiden/docs

ci(docs): validate aggregated Docusaurus build on pull requests

Aperta
#358 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
Lingua principale
TypeScript
Stelle
10
Fork
50
Merge medio
22g 23h
PR unite (30g)
1

Descrizione

### What should be done?

Add a read-only pull request check that builds the same aggregated Docusaurus site produced by `.github/workflows/deploy-docs.yml`.

A checkout of this repository alone does not contain all of the documentation referenced by the sidebar. The deploy workflow first ingests content from the protocol, tutorials, client, node, note transport, bridge portal, VM, compiler, and Guardian repositories, then runs `npm run build`. Because that workflow runs on pushes to `main`, manual dispatches, and repository dispatches, integration failures can currently be discovered only after a documentation PR is merged.

### How should it be done?

Proposed scope:

1. Run on pull requests with read-only permissions and no Pages deployment steps.
2. Check out the PR revision of the docs repository.
3. Reuse or extract the aggregation logic from `deploy-docs.yml` so the validation path does not drift from production.
4. Resolve stable external refs for the run, ingest the same source trees, then run `npm ci` and `npm run build`.
5. Report missing source refs explicitly rather than continuing with an incomplete docs tree.

This should remain separate from link normalization in #262 and executable snippet coverage in #337/#342. The goal here is only to validate the assembled site's build boundary.

Before implementing, it would be useful to confirm whether maintainers prefer external refs pinned from the release manifest or the refs currently used by the deploy workflow. If this direction is welcome, I would be happy to take it once assigned.

### When is this task done?

- A valid documentation PR passes an aggregated Docusaurus build before merge.
- Missing sidebar document IDs, invalid MDX/imports, or aggregation errors fail the check.
- A missing external repository/ref produces a clear failure.
- Pull requests from forks can run without repository secrets.
- The check has no `pages: write` or `id-token: write` permission and never deploys.
- Aggregation behavior is shared with, or demonstrably equivalent to, the deploy workflow.

### Additional context

Recent PR #352 repaired a programmatic onboarding path across several pages, but GitHub reports no checks for that PR. On current `main`, the only workflows are the deploy and version-cut workflows; neither provides an aggregated build check for ordinary pull requests.

A raw-checkout `npm run build` is not a useful substitute: the source tree intentionally omits ingested documentation, so the build reports missing sidebar document IDs until aggregation has run. The proposed check therefore needs to validate the assembled site rather than only the authored files in this repository.

Guida per i contributori

Apri la guida per i contributori

Valutazione

Questa issue non è ancora stata valutata.

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.