ci+hub: durable reviewer hub via in-repo HTML + perf-CI matrix on Linux
Some checks failed
C++ Tests / test-fast (pull_request) Successful in 2m16s
API Docs / doc-build (pull_request) Successful in 51s
Markdown link check / check (pull_request) Successful in 45s
C++ Tests / test-cgal (pull_request) Failing after 7m40s
C++ Tests / quality-gates (pull_request) Failing after 2m1s

Two additions that close out the reviewer-prep work cleanly:

1. doc/reviewer/hub.html  +  publish-workflow integration
   ──────────────────────────────────────────────────────
   Move the hand-curated reviewer hub from the codeberg `pages`
   branch (where it lived as an opaque snapshot) into the repo as
   `doc/reviewer/hub.html`.  `.gitea/workflows/doxygen-pages.yml`
   gains a conditional `if [ -f doc/reviewer/hub.html ]; then …`
   step that installs it as the publish `index.html` and demotes
   the auto-generated Doxygen index to `/doxygen.html`.

   Effect: merging any of the open PRs into main will trigger the
   workflow, which republishes BOTH the Doxygen + the reviewer hub
   together.  The reviewer URL stays live across merges with zero
   manual intervention.

   Source-controlled benefits:
     * hub edits go through normal PRs, not orphan-branch
       force-pushes
     * old hub versions live in git history
     * the in-repo links now target `branch/main/…` instead of the
       transient `preview/reviewer-snapshot-vN/…` paths

2. .gitea/workflows/perf-compile-time.yml — Linux CI bench
   ────────────────────────────────────────────────────────
   New workflow runs on every push to main that touches the build
   system or public headers.  Five-step matrix measures and reports:
     Run 1   cold baseline (no PCH, no Unity, no ccache)
     Run 2   + PCH only
     Run 3   + PCH + Unity (current default)
     Run 4   + FAST_TEST_BUILD=ON  (-O0 -g — Linux's expected ~40 % win)
     Run 5   + ccache warm rerun   (expected ≥ 90 % cache hit)

   Validates the Apple-M1 predictions in doc/architecture/compile-time.md
   against the Linux + g++ runner where Backend dominates more and
   the Apple-clang+PCH friction that defeats ccache locally does not
   apply.  Job is data-collection only; never blocks a merge.

doc updates:
  * doc/architecture/compile-time.md — new "Cross-platform perf bench"
    section linking to the workflow + the table of macOS-vs-Linux
    expected deltas.
  * doc/reviewer/README.md — new "Hub-Page durability" subsection
    explaining how the hub survives merges.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Tarik Moussa
2026-05-26 09:11:34 +02:00
parent bc40a13e8d
commit 3f508adf18
5 changed files with 756 additions and 4 deletions

View File

@@ -188,13 +188,31 @@ build:
| `FAST_TEST_BUILD=ON` (Linux CI) | 5 | ~30 (expected) | ~25 (expected) |
| `FAST_TEST_BUILD=ON` (Apple clang) | 5 | 52 | n/a (use DEV_BUILD locally) |
## Cross-platform perf bench (Linux CI)
`.gitea/workflows/perf-compile-time.yml` runs a 5-step matrix on the
eulernest Linux runner after every push to `main` that touches the
build system or public headers. The matrix validates the predictions
that this document makes against the macOS-local measurements:
| Run | Predicted Linux gain | Apple M1 actual |
|---|---|---|
| Baseline (no PCH, no Unity, no ccache) | reference | 78 s |
| + PCH only | ~15 % | 66 s (15 %) |
| + PCH + Unity (default) | ~30 % | 55 s (30 %) |
| + FAST_TEST_BUILD (-O0 -g) | **~40 % vs default** (g++ Backend dominates) | 52 s (neutral on clang) |
| + ccache warm rerun | **≥ 90 % vs default** (8.5× speedup) | 56 s (Apple-clang PCH friction = 0 % hit) |
The job is data-collection only — does not gate merges. Output appears
in the run summary tab; if Linux numbers diverge from predictions, the
"Next levers" table below gets updated based on what actually wins.
## Next levers (not in this branch)
If 55 s wall is still not enough for full-clean rebuilds:
| Lever | Estimated win | Cost |
|---|---|---|
| `-O0` for the CGAL test target in CI PRs | 55 s → ~30 s | 1 h policy doc |
| `extern template` (lever #2 above) | 55 s → ~52 s | 2 h + Eigen version tracking |
| Header split (lever #3) | downstream-only | 1 day + API risk |
| C++20 Modules | speculative; experimental in Apple clang 17 | weeks |