[chrisjsewell]

Merge with "Create a merge commit" — not squash. The whole point is the preserved
history, and merge_commit_title is already Pull request title, so master's
first-parent line reads this pull request's title with no hand-editing.
allow_merge_commit is false today and has to be flipped on immediately before the
merge and off immediately after.

useblocks/sphinx-codelinks moves into this workspace as packages/sphinx-codelinks/,
with its history, its seven release tags and its release path. It is the third
distribution here and the first that depends on another one at runtime.

What the import is

The whole of that repository's main — 110 commits, tip 63adfe50 — is merged in,
rewritten by git filter-repo so that every historical commit already places its files
under packages/sphinx-codelinks/. 207 files, +18 382 lines, and nothing outside the
package. Three things came with it:

• Tags. Its seven releases arrive prefixed: sphinx-codelinks-v0.1.1 …
  sphinx-codelinks-v1.4.0. Here the prefix is load-bearing rather than hygienic:
  release_plan.py reads every tag without -v in it as a sphinx-needs release, and
  three of the seven bare names — 1.1.0, 1.2.0, 1.3.0 — are existing sphinx-needs
  releases. Without the rename the fetch would have moved them.
• A scoped commit-message rewrite. Bare #N references became
  useblocks/sphinx-codelinks#N, 110 of them on main, bounded to the repository's own
  number range (#1–#106). The one already-qualified cross-repository reference,
  useblocks/ubcode-pub#75, is untouched — the rule's lookbehind is what leaves it alone.
  Every remaining # in the history is a Markdown heading or a quoted shell comment, and
  none is followed by a digit.
• The commit map, committed as
  packages/sphinx-codelinks/design/import-commit-map.txt. The rewrite gives every commit
  a new hash, and this project has seven released versions whose GitHub Releases,
  changelog entries and PyPI page are full of the old ones. The old repository will be
  archived, not deleted or transferred, so those permalinks keep serving; this file is what
  carries them across.

How to read the history afterwards

git log packages/sphinx-codelinks/<path> works with no --follow — filter-repo
rewrote the paths, so from this repository's point of view those files were always there.
That is the opposite of the sphinx-needs files the 2026-09 restructure moved, which do need
it. git blame needs nothing either way, and git log --first-parent master shows the
whole import as one line.

If you have an open pull request in the old repository

Its commits move across with their authorship, and as cleanly as your branch merges
with main today. The property that makes it work is that filter-repo's rewrite is
deterministic: filtering your branch with the same rules puts its commits on exactly the
commit this import merged.

Seven of the eight open pull requests conflict with main right now (only #100 does
not), so seven authors will hit a conflict during the cherry-pick — the conflict they
already had, not one the import creates. Rebase your branch onto main in the OLD
repository first and the move is conflict-free.

git clone https://github.com/useblocks/sphinx-codelinks.git pr-move && cd pr-move
git fetch origin '<your branch>:<your branch>'
# for a fork: git fetch https://github.com/<you>/sphinx-codelinks.git '<branch>:<branch>'
printf '%s\n' 'regex:(?<![\w/])#([1-9]|[1-9][0-9]|10[0-6])\b==>useblocks/sphinx-codelinks#\1' > rules.txt
uvx git-filter-repo --to-subdirectory-filter packages/sphinx-codelinks \
    --tag-rename ':sphinx-codelinks-v' --replace-message rules.txt --force
# then, in a checkout of useblocks/sphinx-needs:
git remote add prmove ../pr-move
git fetch prmove '<branch>:refs/remotes/prmove/<branch>'
git checkout -b <branch> origin/master
git cherry-pick $(git merge-base prmove/main prmove/<branch>)..prmove/<branch>

Then resolve anything this branch's later commits touched, and push. The list, most
likely first:

• the member's pyproject.toml — [dependency-groups], [tool.ruff*], [tool.ty*]
  and [tool.pytest.ini_options] no longer exist there; the root owns them. A branch that
  added a test dependency puts it in the ROOT test group instead, and a new extra stays
  in the member's [project.optional-dependencies]. This is the one a branch that touches
  the manifest at all will hit;
• the four __init__.py under src/sphinx_codelinks/;
• the changelog, which moved from docs/development/change_log.rst to docs/changelog.rst;
• analyse/utils.py, if your branch touches the git helpers the #106 fix rewrote.

Proven end to end twice: on sphinx-codelinks#100 (11 commits, 153 files, zero conflicts —
the one branch that is current with main) and on #96, a one-commit fork branch four
commits behind, where exactly one file conflicted (pyproject.toml, for the reason above)
and the other 25 applied cleanly, including a rename cherry-pick followed on its own.

What changed beyond the move

The standalone-repository files retire. .github/ (five workflows), .python-version,
.pre-commit-config.yaml, tox.ini, .vscode/ and .gitignore — the root owns every one
of them, and while the member kept a .pre-commit-config.yaml prek treated it as a project
of its own. The three ignore entries the root lacked (invalid_objs.json, output/,
.ty_cache) moved up; uv.lock deliberately did not, because this workspace tracks its
lock. gh_pages.yml goes with the rest even though the Pages site is still live: the old
repository keeps serving it until the DNS moves, so a copy here would be dead weight. From
the manifest, the tables check_workspace.py check (7) refuses — the pre-import work had
already made them copies of the root's, so nothing about lint, types or collection changes
when they go. Added instead: [project.urls], which this distribution has never had.

The root wiring. The member is listed and sourced from the workspace; docs-codelinks
and codelinks-libclang re-export its extras. The shared test group gains toml (its
CLI tests write toml, and tomllib only reads) and furo (two test fixtures set
html_theme = "furo" and one is built by a test — a test dependency here, not a docs one).
The typing group gains types-Pygments and types-jsonschema, without which five of the
package's # ty: ignore comments suppress nothing and the error-on-warning ratchet
reports them as unused. uv lock adds 29 package names / 31 entries, removes nothing and
moves no existing package's version.

testpaths is deliberately untouched: this package ships a tests/__init__.py like
sphinx-mounts', so adding its path makes the bare root pytest collect nothing rather
than more. The Lint job's "Check a bare root pytest still collects" step already guards it.

Bringing it under the root's ruff cost two import re-sorts, and they are structural.
The root's [tool.ruff] src names packages/sphinx-needs/src, so sphinx_needs is
first-party in this workspace and isort moves it out of the third-party block. This is
the first member whose source imports it — nothing in packages/sphinx-mounts/src does —
so it is a class of change the pre-import convergence could not have anticipated from
outside. The member's one per-file-ignore entry moved to the root scoped to
packages/sphinx-codelinks/tests/*; as **/tests/* it would have loosened the other
three suites too.

Four empty __init__.py. analyse/, source_discover/, sphinx_extension/ and
sphinx_extension/directives/ were PEP 420 namespace directories, so
pkgutil.walk_packages never reported them and import_check.py — the release gate that
imports every module of the built wheel against its dependencies as published — saw
5 of the package's modules and exited 0. With the four files, and with the new
--extra option that gives the walk the optional engine, it reports 24, which is
every .py under src/sphinx_codelinks/ (the four new files included).

Four latent bugs the old repository's CI shape could not see

1. __version__ had read "0.1.0" since the first commit, through seven releases,
while the manifest went to 1.4.0 — so an installed 1.4.0 reported the wrong version. It is
exported in __all__, so it is public API. check_workspace.py check (5) is what caught
it on the first run here, and poe bump keeps the two in step from now on.

2. locate_git_root found no git root in a linked worktree. It required .git to be a
directory, and get_remote_url/get_current_rev then read <root>/.git/config and
<root>/.git/HEAD directly. In a worktree .git is a file holding gitdir: …, the
remotes live in the main repository's git directory named by commondir, and only
per-worktree state is local. The consequence is worse than the missing links the issue
reports: poe docs-codelinks runs -nW, and this repository is worked in worktrees as a
matter of routine, so the documentation build failed for every developer while staying
green in CI and on Read the Docs, which use plain clones. Reverting the fix here gives five
[codelinks.git_root] errors and a red build. Two helpers do it, and a plain checkout takes
exactly the path it took before. The regression test builds a real git worktree in both
shapes git makes — detached, where HEAD is a SHA, and a branch, where it is a ref: into
the common directory. Closes sphinx-codelinks#106.

3. libclang was not actually optional for the suite. It is an optional extra at
runtime, and three test modules guarded it; a fourth imported
sphinx_codelinks.analyse.preproc unguarded, and that package imports the libclang loader
eagerly. So an environment without the wheel failed during collection rather than
skipping. The old CI never saw it because its test group always installed libclang. One
pytest.importorskip line, and the suite now degrades honestly: 359 passed with the
engine, 303 passed / 26 skipped without it — 26 rather than 56, because a module-level
importorskip is one skip per module and never collects the tests inside; 56 is how many
test cases stop running.

And CI asserts the engine is there. extra-groups: codelinks-libclang is the only
executable place that wheel is named, and losing it would be silent: a cell without the
group is green at 303 passed, 26 skipped. So the Extensions cell imports clang.cindex
right after its sync and fails naming the group — the libclang half of the renderer check
the composite already carries, and the same rule the repository already applies to
graphviz and PlantUML.

4. get_current_rev returned None once the refs were packed. It resolved
ref: refs/heads/<x> by looking for a loose ref FILE, and there is none after git gc or
git pack-refs --all — which run unattended on any long-lived checkout. Same red -nW
docs build as #106, reached by a different route, and again invisible to CI and RTD, which
both leave a detached HEAD. It now falls back to packed-refs, with a fixture case that
packs the refs and asserts the sha.

A fifth, smaller one: test_form_https_url passed a filepath relative to the CWD, so
the suite only passed when pytest ran from the package directory. It is fixed rather than
worked around with a working-directory:, which is what lets CI run it from the repository
root like every other cell.

CI

tests-mounts becomes tests-extensions: one cell per sphinx series (ubuntu ×
sphinx-7/8/9, plus one windows-latest cell on sphinx-9) running both extension packages'
suites as steps, each with its own --cov-report=xml:<name>.xml and its own codecov
upload. The names of the checks change and the count does not. One cell for the two of
them rather than a second three-cell matrix because sphinx-codelinks' whole suite is under
20 seconds: as cells of its own it would spend more runner time starting jobs than testing.
The cost is that a failure in the first suite could hide the second, so the second pytest
step runs under !cancelled().

test-package.yaml cannot express two suites and should not learn to — a workflow_call
input is a scalar and a job's steps cannot be generated from data — so test-extensions.yaml
is a second reusable workflow. What would have made that a step backwards is the 57 lines
of prologue the two units share, which is the duplication #1864 existed to remove. So those
move to a composite action, .github/actions/prepare-cell: the renderer installs and
their guards, the Point PLANTUML_JAR at the vendored jar step (#1870's, verifying
vendor/plantuml/ against its pin), the cell sync, the version report and
check_sphinx_cell.py. test-package.yaml is refactored onto it with no change to any
caller's inputs and no change to what a cell does — and test-extensions.yaml needs no
PlantUML wiring of its own, because it already passes needs-plantuml: true and inherits
the verified jar through the composite.

The composite holds run: steps only. dependabot's github-actions ecosystem is what
keeps actions/checkout, astral-sh/setup-uv and codecov/codecov-action pinned and
bumped, and a pin moved inside a composite action stops being seen — so all three stay
written in the two workflows. The one consequence is that setup-uv now runs before the
renderer installs rather than after them; nothing reads across that boundary, and #1870
needed setup-uv first for its own reason anyway (its --verify step runs a python
script), so the two changes converge.

libclang is a dependency group, not part of test. The wheel is 23 MiB and 81 MB on
disk and only 56 of 359 tests use it, so every cell of every package would otherwise pay
for an engine it never calls. The Extensions cell adds --group codelinks-libclang; the
release workflow's compat cell gets it from
packages/sphinx-codelinks/compat-requirements.txt, through the per-member hook the
sphinx-mounts import already added. Without either, the affected tests skip rather than
fail — so both are load-bearing against a quieter green rather than a red.

A new Docs codelinks job builds them on every pull request — one uv sync
and one sphinx-build, mirroring docs.yaml's Docs-Linkcheck idiom rather than going
through poe, which would install the whole dev group as well just to have poe on the
path. The build itself is 7 seconds. Those docs are the one end-to-end exercise of the extension — src-trace runs
over four projects of the package's own source — and nothing else in CI builds them:
docs.yaml is a linkcheck scoped to sphinx-needs' docs, and the Read the Docs pull-request
build is neither a required context nor even run when the package did not change. It is
also what caught the worktree bug. An equivalent for sphinx-mounts is worth having and is
not this pull request's.

codecov.yml gains a codelinks flag with target: auto, as mounts has, until a real
number is known. check gains both new jobs. The bazel lane, tests-core, tests-js,
tests-no-mpl, smoke-needs and concurrency are untouched. Cost: roughly +2 runner
minutes per push — four Extensions cells each about 20 s longer, plus a Docs codelinks
job of about a minute, of which the build itself is 7 s.

What is lost, and accepted

The old ci.yml ran eight pytest cells: py3.11/3.12/3.13/3.14 across sphinx 7/8/9, two
Windows cells, macOS, and ubuntu-24.04-arm. This repository runs one pinned interpreter
for the extension packages and one Windows cell. macOS, arm64 and the per-interpreter
matrix go, and that is a real reduction rather than an oversight — it is the shape this
repository already runs for sphinx-mounts, and the alternative is eight more cells on every
push for a package whose suite is nine seconds. The Windows cell is kept deliberately:
this package does path arithmetic, and three of the five latent bugs above are path
bugs: the packed refs, the worktree gitfile and the CWD-relative test parameter.

And the newly lowered Python floor is exercised by nothing. This pull request ships a
changelog bullet announcing "Python 3.11 is now supported; the floor moves down from 3.12"
— and tests-extensions passes no python-version, so every cell runs on the root pin
(3.13). tests-core's 3.11 rows test sphinx-needs only, the release compat cell uses the
pin too, and check_workspace.py compares requires-python strings without executing
anything. That is this repository's existing shape for sphinx-mounts as well, which is why
it is accepted here rather than fixed in this pull request; #1865 is the workspace-level
issue for it.

Also gone: the old Documentation build job, replaced by the Docs codelinks job above,
and the standalone coverage.yaml, folded into the Extensions cell's flag.

Read the Docs

packages/sphinx-codelinks/.readthedocs.yaml is re-rooted — every path in it is relative
to the repository root, which is RTD's documented monorepo rule — and it carries the
post_checkout job that exits 183 when nothing under the package changed. sphinx-mounts'
import deferred that because RTD's commit-status behaviour for a cancelled build was
unverified; it has since been measured (build 34411602: cancelled, and a success status
on GitHub), so this one has it from the start.

docs/conf.py and docs/ubproject.toml named the old repository in five places — furo's
view/edit buttons and the four remote_url_pattern entries src-trace uses. All five now
name this repository, with source_directory = "packages/sphinx-codelinks/docs/". {path}
needed no change: it is computed relative to the git root, so a built page's blob link comes
out as
…/sphinx-needs/blob/<sha>/packages/sphinx-codelinks/tests/data/dcdc/charge/demo_1.cpp#L16.

After the merge

1. Create the label pkg: sphinx-codelinks — before the MERGE, and before the issue
   transfers in step 3, which cannot apply a label that does not exist. It is not needed
   for this pull request's own CI: label-prs.yaml runs as pull_request_target, so it
   reads .github/labeler.yml from master, which has no pkg: sphinx-codelinks entry
   until this merges — the labeler never tries to apply it here and stays green (it applies
   pkg: workspace, which this pull request earns). By the same token the new
   labeler.yml entry is unproven until the first pull request after the merge. Match the
   existing convention (pkg: sphinx-mounts is #0E8A16, pkg: sphinx-needs #1D76DB,
   pkg: workspace #5319E7), each with a one-line description.

2. Push the seven tags — git push origin 'refs/tags/sphinx-codelinks-v*'.
   Deliberately after, not before: pushed early they would make the codelinks commits
   reachable while the code is not on master, and release_plan.py would already report a
   third member.

3. The issues. Nineteen of the old repository's 21 open issues transfer; transfer needs
   write access on both repositories, so it must happen before archiving, and
   pkg: sphinx-codelinks must exist first or it cannot be applied in the same pass. Do
   not pass createLabelsIfMissing — every label those issues carry already exists
   here, so they survive the transfer by name. Two do not transfer:

   • needs_title_from_content stops too early #106 (locate_git_root in a worktree) is fixed by this pull request — close it
     with a pointer;
   • Add needed import statement to needs_extra_options #67 ("Support Sphinx 9") is already true — the manifest says sphinx>=7.4,<10 and
     the sphinx-9 cell is green. Close it with the evidence.

   Two open pull requests carry an issue number in their title (needimport: Sort the imported needs using natural sort order #82 says "issue needs_template and needs_template_collapse removed? #69",
   ID option does not support dyn. functions #99 says "(IDs are forced to uppercase. #43)"). A transfer does not rewrite PR titles, because the PRs do not move —
   fix those by hand when they are re-opened here.

4. The eight open pull requests. None is mergeable as it stands: seven conflict with
   main and one is merely behind. Their authors move them with the recipe above, or close
   them with a pointer — the branches stay readable in the archived repository. Two
   decisions are worth taking at the freeze rather than later: Bug: dyn. func. copy() not working with tags #100 (test
   infrastructure, the only mergeable one) and the three overlapping marked-RST pull
   requests Wrong error message for missing link #44 / Need copy/mirror: Showing the same need at different places #66 / ID option does not support dyn. functions #99, which are three implementations of one issue.

5. Read the Docs, in this order, because RTD's automation rules run when a version is
   created and both recommended actions build it:
   a. the seven tags are pushed first (step 2), so RTD's initial sync creates those seven
   versions before any rule exists — a rule added first would activate and build all
   seven, and all seven would fail, because their trees predate this
   .readthedocs.yaml;
   b. create the project against this repository; set Admin → Settings → Build
   configuration file to packages/sphinx-codelinks/.readthedocs.yaml. Do not touch the
   sphinx-needs project's setting — it applies to every version that project builds;
   c. let the default latest build go green once;
   d. add the two automation rules on ^sphinx-codelinks-v\d+\.\d+\.\d+$ — Activate
   version and Set version as default. RTD derives stable with
   packaging.version.Version(<tag>) and drops what it cannot parse; a prefixed tag is
   not PEP 440, so without the second rule the project never gets a default;
   e. docs/readthedocs.org:sphinx-codelinks must not become a required status context.
   The exit-183 job makes that build absent on most pull requests, and a required context
   that never reports blocks the merge. Same reason the sphinx-mounts one is not required.

6. The redirects, and then the domain. Four external repositories link deep into
   codelinks.useblocks.com today (/basics/installation.html,
   /components/configuration.html, /components/analyse.html#marked-rst-blocks), and
   those paths gain an /en/stable/ prefix under RTD. Add the redirects before the DNS
   switch — /basics/$rest, /components/$rest, /development/$rest and
   /objects.inv → /en/stable/…; objects.inv matters because this project is an
   intersphinx target. Then add codelinks.useblocks.com as an RTD custom domain and move
   the DNS CNAME off useblocks.github.io. Until that last step the OLD repository's Pages
   deployment IS the live site, so there is no window with no site — and only after it is
   the old gh_pages.yml genuinely dead.

7. Archive the old repository — never delete, never transfer. Seven real
   git+https://github.com/useblocks/sphinx-codelinks.git@… pins exist in the wild, in
   four repositories. An archived repository stays public and clonable read-only, so all
   seven keep resolving; deleting it breaks every one, along with every blob permalink to a
   pre-rewrite hash. Three of the four are useblocks' own (bazel-drives-sphinx,
   needs-large-scale, ubtrace) and should re-point at PyPI or at
   git+https://github.com/useblocks/sphinx-needs.git@…#subdirectory=packages/sphinx-codelinks;
   ubtrace's is an @main pin, so it is the one that silently stops receiving updates.

Refs #1803