Repository navigation
Add Pandoc update tooling: --skip-archive and smoke-test override - #15291
Merged
Merged
Conversation
Regenerating the Pandoc reference templates and format-extension.ts needed the full update-pandoc run, which archives the binary to S3 first. Anyone without S3 credentials could not prepare or check a Pandoc bump, so the template diff was always reviewed late, by whoever did the archival. With --skip-archive the command only regenerates templates and format-extension.ts, from the binary QUARTO_PANDOC points at, and leaves configuration untouched. QUARTO_PANDOC is required and its reported version must match the requested one: pandocBinaryPath() falls back to the bundled Pandoc when the override is missing or invalid, and format-extension.ts would then be silently regenerated from the old version.
A Pandoc bump could only be smoke-tested in CI once the new binary was archived to S3 and configuration pointed at it. The new pandoc-override-version dispatch input installs that release from GitHub and points quarto at it through QUARTO_PANDOC for the run only, so rendering changes can be checked before archival. The steps live in a composite action, placed after quarto is installed so the final `quarto pandoc --version` check works in every quarto-install mode. README indexes list the composite actions in both action directories.
Each format's pandoc/ directory holds both Quarto's real templates (template.tex, common.latex, styles.html, ...) and verbatim copies of Pandoc's own (latex.common, html.styles, typst.template, ...) that no code reads. Their names differ only by segment order, and the docs described some reference copies as if they were rendered. Template fixes have landed in the reference copy instead of the wired file because of this. The checklist now splits the update into a prep phase anyone can do (--skip-archive, the smoke-test override) and an archival phase for the S3 credential holder, and lists the wired and reference files per format. The llm-docs and path-scoped rules get the same correction, and a rule points configuration bumps to the dependency docs.
Collaborator
✅ Snyk checks have passed. No issues have been found so far.
💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse. |
… override)
The new Deno.env.get("QUARTO_PANDOC") in package/src/common/update-pandoc.ts
raises the package/src count from 240 to 241. src/deno_ral has no env
accessor yet, and package/src already reads QUARTO_PANDOC the same way in
update-html-dependencies.ts, so there is nothing to migrate in this PR.
Bump the baseline so the runtime-boundary check accepts the count.
Describe the required Pandoc override and the next action directly. Keep the full update procedure in the checklist so command output stays concise.
Keep reference-copy maintenance in the update checklist and point related architecture notes to it. Split the Typst writer example into shorter explanations and scope the bundled-version statement to the configured version.
A test-smokes.yml dispatch with pandoc-override-version intentionally runs the suite against a Pandoc newer than the bundled one, while check.ts's strict constraint still names the archived version (Phase 1 keeps it unchanged on purpose). check-versions-no-mismatch.test.ts then failed on the expected "does not strictly match" note, turning a successful full-suite override run red. The pandoc-override action now exports the requested version as QUARTO_TEST_EXPECTED_PANDOC (alongside QUARTO_PANDOC). The test requires the Pandoc note to name exactly that version when set - proving the override binary is live - and keeps the no-mismatch assertion for Dart Sass, Deno, Typst, and for Pandoc on normal runs. Also cover macOS in the action: the QUARTO_PANDOC export steps were Linux/Windows-only, so an override dispatch with a macOS runner would silently test the bundled Pandoc there while the version test (and any rendering assertion) assumed the override.
Follow-up to f8a0a9d addressing its re-review: - Dispatching with pandoc-override-version equal to the current release (e.g. 3.10) is a valid run - a plumbing check or a tag typed without the patch component - but check versions reports "Pandoc version 3.10.0: OK" there, not a mismatch note, and requiring the note failed the run. The assertion now accepts either line, as long as it names exactly the requested version; a wrong binary still fails. - The test's new Deno.env.get raises tests.denoCalls from 774 to 775 (counted with the checker's own regex: 0 before, 1 after); accept the increase in the baseline, same as 5f0fc58 did for package/src.
Describe both accepted override outcomes and the normalized version comparison so the test comments match its assertions. Make the regeneration review instructions explicit and keep the template documentation focused on lasting guidance.
Keep the dependency rule focused on the detailed checklists and shorten the override descriptions. Remove the test comment that repeats the override contract above.
Keep the localization example next to its introduction and shorten the writer explanation. Remove a comment that repeats the adjacent version verifier.
2 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Salvages the tooling and docs half of #14728, which prepared a Pandoc 3.10.1 bump that is now superseded by the upcoming 3.13 update. Its template resyncs and version bump are dropped, as 3.13 regenerates those files. The rest is useful for any Pandoc update and was never on main, since #14723 (the earlier merge of the same branch) was reverted.
Updating Pandoc needs S3 credentials for the archival step, and until now everything else depended on it: the template and
format-extension.tsregeneration ran only as part of the archival command, and CI could smoke-test a new Pandoc only after the binary was archived. Most of the update work can now happen before archival, by anyone.Changes
quarto-bld update-pandoc <version> --skip-archiveregenerates the Pandoc reference templates andsrc/core/pandoc/format-extension.tsfrom the binaryQUARTO_PANDOCpoints at, without archiving or touchingconfiguration. It fails whenQUARTO_PANDOCis unset or reports another version, because the tool lookup silently falls back to the bundled Pandoc and would regenerateformat-extension.tsfrom the old one.test-smokes.ymlgets apandoc-override-versiondispatch input. A new composite action installs that Pandoc release from GitHub and setsQUARTO_PANDOCfor the run.dev-docs/update-pandoc-checklist.mdsplits the update into a prep phase and an archival phase, and lists for each format which files are Quarto's wired templates and which are verbatim copies of Pandoc's that no code reads (latex.commonvscommon.latex,html.stylesvsstyles.html, ...). The names differ only by segment order and the llm-docs described some reference copies as rendered, so fixes landed in the wrong file. The llm-docs and path-scoped rules get the same correction.Test plan
QUARTO_PANDOC=/path/to/pandoc-3.13 ./package/src/quarto-bld update-pandoc 3.13 --skip-archiveon main regenerates exactly the six reference copies changed by the 3.13 update commit, byte-identical, and noformat-extension.tschange3.12, and withQUARTO_PANDOCunset, fails with an errortest-smokes.ymlwithpandoc-override-version: 3.13and confirm the run reports Pandoc 3.13Checklist
I have (if applicable):
AI-assisted PR
Note: autonomous AI agents submitting PRs without human oversight are not permitted — see the Code of Conduct.