diff --git a/.claude/rules/extension-subtrees.md b/.claude/rules/extension-subtrees.md new file mode 100644 index 00000000000..e235c16de2a --- /dev/null +++ b/.claude/rules/extension-subtrees.md @@ -0,0 +1,30 @@ +--- +paths: + - src/resources/extension-subtrees/** +--- + +# Extension Subtrees + +Files under `src/resources/extension-subtrees//` are git subtrees from external repos. **Do NOT edit directly here.** + +Current subtrees (see [`src/command/dev-call/pull-git-subtree/cmd.ts`](../../src/command/dev-call/pull-git-subtree/cmd.ts) for the source of truth): + +| Name | Upstream repo | +|---|---| +| `julia-engine` | `PumasAI/quarto-julia-engine` | +| `orange-book` | `quarto-ext/orange-book` | + +## Workflow + +1. Open a PR with the fix in the upstream repo +2. Wait for upstream merge +3. From quarto-cli, run: + ```bash + quarto dev-call pull-git-subtree + ``` +4. The command adds two commits (squash + merge) — **do not edit those commits** +5. **Do not rebase** a branch that contains the subtree-pull commits — they cannot be rebased cleanly. Merge to `main` without rebasing, or remove the two commits before rebasing and re-run the pull command. + +## Reference + +Full workflow: [`dev-docs/subtree-extensions.md`](../../dev-docs/subtree-extensions.md) diff --git a/dev-docs/subtree-extensions.md b/dev-docs/subtree-extensions.md index 5ed7f0a03af..d757142c252 100644 --- a/dev-docs/subtree-extensions.md +++ b/dev-docs/subtree-extensions.md @@ -1,6 +1,6 @@ # Subtree extensions -Subtree extensions live in `src/resources/subtree-extensions`. +Subtree extensions live in `src/resources/extension-subtrees`. Each is the complete git repository of a Quarto extension, e.g. the directory tree for the Julia engine looks like @@ -14,6 +14,20 @@ src/resources/extension-subtrees/ ... ``` +The list of subtrees and their upstream repos lives in the `SUBTREES` table in [`src/command/dev-call/pull-git-subtree/cmd.ts`](../src/command/dev-call/pull-git-subtree/cmd.ts). + +## Updating an extension + +Fixes to extension files **must be authored upstream**, never edited directly inside `src/resources/extension-subtrees//`. The correct workflow: + +1. Open a PR with the fix in the upstream repo (e.g. `quarto-ext/orange-book`, `PumasAI/quarto-julia-engine`) +2. Merge the PR upstream +3. From quarto-cli, run the pull command (see [Pulling subtree updates](#pulling-subtree-updates)) + +Editing directly inside the subtree prefix is wrong: the change will be overwritten the next time the subtree is pulled, and anyone who forked the upstream extension will not benefit from it. + +## Pulling subtree updates + The command to add or update a subtree is ``` @@ -39,3 +53,37 @@ So you must either - run the command when ready to merge to main, or - remove the commits when rebasing, and run the `dev-call` command again + +## Recovery: edits made in-tree by mistake + +If a fix has already been committed directly inside the subtree prefix (wrong workflow), it needs to be re-authored upstream before resuming the normal flow. Two paths: + +### Option A — re-author upstream manually (recommended) + +Faster and more predictable, especially in repos with many commits where `git subtree split` walks the full history. + +1. Clone the upstream repo locally (e.g. `git clone https://github.com/quarto-ext/orange-book.git`) +2. Create a feature branch from upstream `main` +3. Apply the same change at the upstream repo's path (the subtree's `_extensions/...` becomes the repo root) +4. Commit (preserve original author and message) and push to the upstream repo +5. Open a PR upstream and merge + +### Option B — `git subtree push` + +Extracts the prefix-scoped history into a synthetic branch and pushes it. Works but is slow on large repos (the split walks every commit) and untested in this codebase. + +``` +git fetch +git subtree push --prefix=src/resources/extension-subtrees/ \ + +``` + +Then open a PR upstream from ``. + +### After the upstream PR merges + +Back in quarto-cli, on the branch holding the original in-tree commit: + +1. Remove the in-tree edit from the local commit (amend or rebase out the lines under the subtree prefix) so `pull-git-subtree` does not conflict with itself +2. Run `quarto dev-call pull-git-subtree ` to bring the upstream change in via the normal two-commit pattern +3. Merge the branch to `main` without rebasing (the subtree-pull commits cannot be rebased — see [Pulling subtree updates](#pulling-subtree-updates)) diff --git a/llm-docs/localization-architecture.md b/llm-docs/localization-architecture.md index a366b435602..768b79068bd 100644 --- a/llm-docs/localization-architecture.md +++ b/llm-docs/localization-architecture.md @@ -1,6 +1,6 @@ --- -main_commit: 4aa86e524 -analyzed_date: 2026-05-20 +main_commit: eca40cdab +analyzed_date: 2026-05-21 key_files: - src/resources/language/_language.yml - src/resources/language/_language-fr.yml @@ -204,7 +204,7 @@ Localization paths: 2. **Pandoc template `$var$` via meta** — same channel as HTML. - `$toc-title$` (resolved via 2b in `pandoc.ts:498`) used in `typst-show.typ:93-95` as `toc_title:`. - `$labels.abstract$` (written by `authors.lua` `computeLabels`) used in `typst-show.typ:30` as `abstract-title:`. - For orange-book (`src/resources/extension-subtrees/orange-book/_extensions/orange-book/typst-show.typ`): as of this writing the template still uses the legacy channel-2b form `$if(crossref.lof-title)$$crossref.lof-title$$else$$crossref-lof-title$$endif$` (and similarly for `lot-title`) to set `list-of-figure-title` and `list-of-table-title` on `book.with(...)`. The fallback `$crossref-lof-title$` resolves against `format.metadata` (channel 2b), so on writers like `+yaml_metadata_block` it can leak into the rendered markdown YAML header. There is no `supplement-chapter` argument wired today. Migration of orange-book's `typst-show.typ` to the `$quarto.language.*$` form (channel 2d), including adding `supplement-chapter`, is tracked at GitHub #14524 — once that lands the leakage path disappears. + For orange-book (`src/resources/extension-subtrees/orange-book/_extensions/orange-book/typst-show.typ`): the template uses the channel-2d form `$quarto.language.crossref-lof-title$` / `$quarto.language.crossref-lot-title$` / `$quarto.language.crossref-ch-prefix$` for `list-of-figure-title`, `list-of-table-title`, and `supplement-chapter` on `book.with(...)`. The `lof` and `lot` pipes use nested `$if(...)$` guards so pre-#14530 Quarto omits the argument entirely and `book()`'s built-in defaults apply. User-override path via the `crossref:` block (`$crossref.lof-title$` / `$crossref.lot-title$`) is preserved as the first cascade branch. Migration shipped via #14525 and [quarto-ext/orange-book#4](https://github.com/quarto-ext/orange-book/pull/4). 3. **Lua-injected supplements for refs** — `crossref/refs.lua:89-91` wraps every `@fig-foo`-style reference into `#ref(