From d0a5a4a381781416b67aaf9c8f774ca9214b39ff Mon Sep 17 00:00:00 2001 From: Thomas Schmelzer Date: Mon, 24 Aug 2026 18:46:28 +0400 Subject: [PATCH 1/2] chore: bump rhiza to v1.6.0 --- .rhiza/template.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.rhiza/template.yml b/.rhiza/template.yml index 5e536913..c452b691 100644 --- a/.rhiza/template.yml +++ b/.rhiza/template.yml @@ -1,5 +1,5 @@ repository: "jebel-quant/rhiza" -ref: "v1.5.2" +ref: "v1.6.0" profiles: - github-project From 8b807185688ddefca84e62fe16376cb9349a48e6 Mon Sep 17 00:00:00 2001 From: Thomas Schmelzer Date: Mon, 24 Aug 2026 18:48:49 +0400 Subject: [PATCH 2/2] chore: apply rhiza sync v1.6.0 --- .github/workflows/rhiza_benchmark.yml | 2 +- .github/workflows/rhiza_book.yml | 2 +- .github/workflows/rhiza_ci.yml | 2 +- .github/workflows/rhiza_codeql.yml | 2 +- .github/workflows/rhiza_marimo.yml | 2 +- .github/workflows/rhiza_paper.yml | 27 +++--- .github/workflows/rhiza_scorecard.yml | 2 +- .github/workflows/rhiza_weekly.yml | 2 +- .rhiza/template.lock | 6 +- cliff.toml | 15 +++- docs/paper/README.md | 125 ++++++++++++++++---------- 11 files changed, 115 insertions(+), 72 deletions(-) diff --git a/.github/workflows/rhiza_benchmark.yml b/.github/workflows/rhiza_benchmark.yml index ca4bd1eb..27347811 100644 --- a/.github/workflows/rhiza_benchmark.yml +++ b/.github/workflows/rhiza_benchmark.yml @@ -20,5 +20,5 @@ on: jobs: benchmark: - uses: jebel-quant/rhiza/.github/workflows/rhiza_benchmark.yml@v1.5.2 + uses: jebel-quant/rhiza/.github/workflows/rhiza_benchmark.yml@v1.6.0 secrets: inherit diff --git a/.github/workflows/rhiza_book.yml b/.github/workflows/rhiza_book.yml index 5a6298eb..72d6feb1 100644 --- a/.github/workflows/rhiza_book.yml +++ b/.github/workflows/rhiza_book.yml @@ -29,7 +29,7 @@ permissions: jobs: book: - uses: jebel-quant/rhiza/.github/workflows/rhiza_book.yml@v1.5.2 + uses: jebel-quant/rhiza/.github/workflows/rhiza_book.yml@v1.6.0 secrets: inherit permissions: contents: read diff --git a/.github/workflows/rhiza_ci.yml b/.github/workflows/rhiza_ci.yml index 1f21c4ed..17995fc4 100644 --- a/.github/workflows/rhiza_ci.yml +++ b/.github/workflows/rhiza_ci.yml @@ -26,5 +26,5 @@ on: jobs: ci: - uses: jebel-quant/rhiza/.github/workflows/rhiza_ci.yml@v1.5.2 + uses: jebel-quant/rhiza/.github/workflows/rhiza_ci.yml@v1.6.0 secrets: inherit diff --git a/.github/workflows/rhiza_codeql.yml b/.github/workflows/rhiza_codeql.yml index 2577e2ac..31452f28 100644 --- a/.github/workflows/rhiza_codeql.yml +++ b/.github/workflows/rhiza_codeql.yml @@ -26,7 +26,7 @@ on: jobs: codeql: - uses: jebel-quant/rhiza/.github/workflows/rhiza_codeql.yml@v1.5.2 + uses: jebel-quant/rhiza/.github/workflows/rhiza_codeql.yml@v1.6.0 secrets: inherit permissions: security-events: write # Upload CodeQL results to code scanning diff --git a/.github/workflows/rhiza_marimo.yml b/.github/workflows/rhiza_marimo.yml index cfbb75b1..a056eff4 100644 --- a/.github/workflows/rhiza_marimo.yml +++ b/.github/workflows/rhiza_marimo.yml @@ -28,5 +28,5 @@ on: jobs: marimo: - uses: jebel-quant/rhiza/.github/workflows/rhiza_marimo.yml@v1.5.2 + uses: jebel-quant/rhiza/.github/workflows/rhiza_marimo.yml@v1.6.0 secrets: inherit diff --git a/.github/workflows/rhiza_paper.yml b/.github/workflows/rhiza_paper.yml index 549e4f5b..b8ebbfaf 100644 --- a/.github/workflows/rhiza_paper.yml +++ b/.github/workflows/rhiza_paper.yml @@ -4,15 +4,18 @@ # Workflow: Paper # # Purpose: Compile the LaTeX paper (docs/paper/*.tex) to a PDF and publish it -# as a downloadable workflow artifact. The durable copy is published by -# the book: `paper` is a prerequisite of `book`, and docs/paper/ sits -# inside the docs tree, so the PDF ships as a site asset. +# three ways: as a downloadable workflow artifact, as a site asset +# through the book (the paper folder sits inside the docs tree), and on +# the dedicated `paper` branch, which holds the PDF and nothing else. # -# It no longer pushes to an orphan `paper` branch (rhiza #1494): that -# ref cannot coexist with any `paper/` branch, so the push failed -# in exactly the repositories most likely to have one. A repository that -# still has the branch gets a warning naming it; delete it when nothing -# links to it. +# The compile is the `paper` task from the pinned rhiza-task CLI -- the +# same one `make paper` runs locally -- so the engine and the choice of +# root document are defined once, not restated per platform. +# +# One caveat on the branch: git refs are paths, so `refs/heads/paper` +# cannot coexist with a `paper/` branch. The workflow checks for +# one and fails with a message naming it rather than with a bare push +# error; rename the topic branch if you hit that. # # Trigger: On push/PR to main/master when docs/paper/** changes, or manual dispatch. @@ -36,9 +39,9 @@ on: jobs: paper: - uses: jebel-quant/rhiza/.github/workflows/rhiza_paper.yml@v1.5.2 + uses: jebel-quant/rhiza/.github/workflows/rhiza_paper.yml@v1.6.0 secrets: inherit - # `contents: read` only. The `write` scope this stub used to grant existed solely for - # the retired branch push; compiling and uploading an artifact need no write access. + # `contents: write` is for the `paper` branch publish and nothing else. A pull request + # never reaches that step, so the scope is unused on every PR run. permissions: - contents: read + contents: write diff --git a/.github/workflows/rhiza_scorecard.yml b/.github/workflows/rhiza_scorecard.yml index 284e8372..ff5b4100 100644 --- a/.github/workflows/rhiza_scorecard.yml +++ b/.github/workflows/rhiza_scorecard.yml @@ -36,7 +36,7 @@ permissions: read-all jobs: scorecard: - uses: jebel-quant/rhiza/.github/workflows/rhiza_scorecard.yml@v1.5.2 + uses: jebel-quant/rhiza/.github/workflows/rhiza_scorecard.yml@v1.6.0 secrets: inherit permissions: security-events: write # Upload the SARIF results to code scanning diff --git a/.github/workflows/rhiza_weekly.yml b/.github/workflows/rhiza_weekly.yml index 03a92fec..bc4b9c23 100644 --- a/.github/workflows/rhiza_weekly.yml +++ b/.github/workflows/rhiza_weekly.yml @@ -28,5 +28,5 @@ on: jobs: weekly: - uses: jebel-quant/rhiza/.github/workflows/rhiza_weekly.yml@v1.5.2 + uses: jebel-quant/rhiza/.github/workflows/rhiza_weekly.yml@v1.6.0 secrets: inherit diff --git a/.rhiza/template.lock b/.rhiza/template.lock index 6377c0c3..c5648926 100644 --- a/.rhiza/template.lock +++ b/.rhiza/template.lock @@ -1,7 +1,7 @@ -sha: bb365b643155b80d93bbd9c20fb9e55f42f1fb33 +sha: e556617285b215566e563c58022c3a031e870aad repo: jebel-quant/rhiza host: github -ref: v1.5.2 +ref: v1.6.0 include: [] exclude: - SECURITY.md @@ -46,5 +46,5 @@ files: - pytest.ini - ruff.toml - tests/test_rhiza_packaging.py -synced_at: '2026-08-24T04:41:54Z' +synced_at: '2026-08-24T14:47:29Z' strategy: merge diff --git a/cliff.toml b/cliff.toml index 6b1e880a..86fbf84a 100644 --- a/cliff.toml +++ b/cliff.toml @@ -64,8 +64,19 @@ sort_commits = "oldest" # Group commits into changelog sections. The leading HTML comment controls the # section ordering and is stripped from the rendered heading via `striptags`. commit_parsers = [ - # Drop automated noise commits that don't provide user-facing signal. - { message = ".*\\[skip ci\\].*", skip = true }, + # Drop automated noise commits that don't provide user-facing signal -- the machine-written + # `Update the compiled paper [skip ci]` kind, which puts the marker in its *subject*. + # + # Anchored to the subject line, and that is load-bearing rather than tidy. git-cliff matches + # this against the whole message, so the unanchored `.*\[skip ci\].*` also dropped any commit + # whose *body* merely mentioned the marker -- a commit message quoting the format of another + # commit message is enough. That silently ate `feat: give the paper branch a README` (#1626) + # out of v1.6.0's notes, for one backticked mention twenty lines down. Same failure as the + # `bump` alternative below: a substring search treating a mention as the thing itself. + # + # `^` with no `(?m)` is start-of-message, and `[^\n]*` cannot cross a newline, so only the + # subject can match. + { message = "^[^\\n]*\\[skip ci\\]", skip = true }, # Only the release flow's own commits. A bare `bump` alternative here also ate every # `chore(deps): bump ` — the rhiza-hooks v1.2.0 bump (#1487) vanished from # v1.3.2's notes that way, and had been vanishing for a while unnoticed: a Dependabot diff --git a/docs/paper/README.md b/docs/paper/README.md index c71fd29b..e5884074 100644 --- a/docs/paper/README.md +++ b/docs/paper/README.md @@ -1,8 +1,7 @@ # LaTeX Paper This folder is where the `paper` bundle expects your LaTeX sources. `make paper` -compiles them to a PDF with `latexmk`, and `make paper-clean` removes the build -artifacts. +compiles them to a PDF, and `make paper-clean` removes the build artifacts. ## Layout @@ -34,22 +33,30 @@ common case. Name it `main.tex` if you have several and want to be explicit. | target | does | | --- | --- | -| `make paper` | `latexmk -pdf -bibtex -interaction=nonstopmode` on the root document | -| `make paper-clean` | `latexmk -C` — removes the PDF and every auxiliary file | +| `make paper` | compiles the root document to a PDF beside its source | +| `make paper-clean` | removes each document's PDF and auxiliary files | -`latexmk` reruns pdflatex and bibtex until the cross-references and citations -converge, so one invocation is enough however many passes the document needs. Both -targets run with this folder as the working directory, so `\input` paths are relative -to it and the auxiliary files land beside the source rather than at the repository -root. +The engine reruns the TeX pass and bibtex until the cross-references and citations +converge, so one invocation is enough however many passes the document needs. `paper` +runs with this folder as the working directory, so `\input` paths are relative to it +and the output lands beside the source rather than at the repository root — which is +what lets the book publish the PDF with no copy step. + +`paper-clean` is scoped by document stem: `paper.tex` authorises deleting `paper.pdf` +and `paper.log`, while a `figures/diagram.pdf` you committed has no `.tex` beside it +and survives. ## Requirements -A LaTeX distribution providing `latexmk` — [MacTeX](https://www.tug.org/mactex/) on -macOS, [TeX Live](https://www.tug.org/texlive/) elsewhere. Without it both targets -skip with that as the reason rather than failing, so a contributor who does not build -the paper is not blocked by it. Pass `--strict` to turn the skip into a failure where -the paper *must* build, such as in CI. +[tectonic](https://tectonic-typesetting.github.io/), a single binary that resolves +the packages a document cites out of its own web bundle and caches them — so there is +no TeX distribution to install and no package list to keep in step with your +`\usepackage` lines. A cold cache needs the network; after that it does not. + +Without tectonic on `PATH` both targets skip, with that as the reason, rather than +failing — so a contributor who does not build the paper is not blocked by it. Pass +`--strict` to turn the skip into a failure where the paper *must* build, such as in +CI, which is what the shipped pipelines do. ## Configuration @@ -63,37 +70,59 @@ paper-folder = "manuscript" ## Continuous integration -The `github-paper` bundle adds a workflow that compiles the paper and publishes the -PDF as a build artifact. It triggers only on changes under `docs/paper/**`, so it -costs nothing until there is a paper to build. - -The **durable** copy comes from the book rather than that artifact, which expires after -30 days. `paper` is a prerequisite of `book`, and this folder sits inside the docs tree, -so mkdocs sweeps the compiled PDF up as a site asset at a stable URL. Link it from the -nav to make it reachable: - -```yaml -nav: - - Paper: paper/main.pdf -``` - -### If your repository has a `paper` branch - -The workflow used to push the PDF to an orphan `paper` branch as well. **It no longer -does**, and a repository that still has the branch will see a warning naming it. - -The push was removed because git refs are paths: `refs/heads/paper` cannot exist while -`refs/heads/paper/anything` does. So opening a `paper/overview` topic branch — the most -natural convention for the very feature this bundle serves — broke the push outright, and -it stayed broken after that topic branch was merged, until somebody also deleted it. - -Nothing needs to change on your side unless something *reads* that branch — a badge, a -Pages source, a direct link. Point those at the PDF in the built site instead, then delete -the branch, which is now nobody's job to update: - -```bash -git push origin --delete paper -``` - -Leaving it in place is harmless except that it holds a PDF frozen at the last run before -this change, with nothing indicating so. +The `github-paper` bundle adds a workflow that compiles the paper and publishes it. It +triggers only on changes under `docs/paper/**`, so it costs nothing until there is a +paper to build. It installs tectonic itself; the compile is the same `paper` task you +run locally, under `--strict`, so a runner that never got the engine fails instead of +reporting a skipped build as success. + +The PDF is published three ways, which is deliberate — they fail differently: + +1. **The run artifact**, named `paper`. Immediate, and it expires after 30 days. +2. **The book.** `paper` is a prerequisite of `book` and this folder sits inside the + docs tree, so mkdocs sweeps the PDF up as a site asset at a stable URL. Link it + from the nav to make it reachable: + + ```yaml + nav: + - Paper: paper/main.pdf + ``` + +3. **The `paper` branch**, which holds the compiled PDF and a generated `README.md` + explaining what the branch is — and nothing else. Pushed on every default-branch run, + never from a pull request. This is the copy you can link without building the site and + without an unexpired run. + + The README is written by the workflow, so anything you commit there by hand is + overwritten on the next run. It deliberately carries no run number or timestamp: that + would make the file differ every time, and the branch would collect a commit per push + whether or not the paper changed. The source commit each PDF was built from is named in + the commit message instead. + + For the same reason the compile pins `SOURCE_DATE_EPOCH` to the source commit's time. + tectonic otherwise stamps the PDF `/ID` from the build time, so an unchanged document + compiles to different bytes on every run — which would commit every time regardless of + the README. With it, a rebuild of a revision you have already published is a no-op. + + Nothing needs to be tracked for this to work — the template gitignores + `docs/paper/*.pdf`. If you commit your PDF anyway, the publish still works; it discards + the freshly compiled copy from the working tree after staging it, which is the only way + to switch branches with a modified tracked file in the way. + +The GitLab pipeline publishes the first two. It does not push the branch: that needs a +token `CI_JOB_TOKEN` cannot stand in for, and this template sets up no project secret. + +### If your repository has a `paper/` branch + +Then the branch publish cannot work, and the workflow says so instead of failing +obscurely. Git refs are paths: `refs/heads/paper` cannot exist while +`refs/heads/paper/overview` does — the most natural branch convention for the very +feature this bundle serves. A preflight step lists the colliding ref and fails with it +named; git's own error on that push names neither branch. + +Your options, in the order most repositories want them: + +1. Rename the topic branch — `paper/overview` → `paper-overview`. +2. Leave it, and take the other two copies. The compile and the artifact upload run + before the preflight, so the PDF is still attached to the failed run and still + published by the book. Only the branch step is red.