🔧 Eight pull requests were open in sphinx-codelinks at the import: decide which move across

[chrisjsewell]

When sphinx-codelinks was imported (#1871), eight pull requests were open in the old repository. Each carries a note pointing at the move recipe in #1871's description ("If you have an open pull request in the old repository"), and the old repository is frozen behind its pinned notice (useblocks/sphinx-codelinks#107). This issue holds the list and the decisions, so nothing is lost while they wait.

old PR	author	size	state against the old main	notes
useblocks/sphinx-codelinks#44 — need items from marked RST in source	juiwenchen	32 commits, 35 files, +1196/−64	conflicting; changes requested	one of three marked-RST approaches
useblocks/sphinx-codelinks#66 — render full RST need directives from @rst blocks	chrisjsewell	1 commit, 15 files, +606/−5	conflicting; draft	one of three marked-RST approaches
useblocks/sphinx-codelinks#82 — TypeScript and JavaScript comment types	arnoox	24 commits, 27 files, +1092/−83	conflicting	closes the transferred TypeScript issue
useblocks/sphinx-codelinks#93 — -W/--strict and shared suppress_warnings	ubmarco	10 commits, 14 files, +670/−25	conflicting; draft	a twin flag is in useblocks/sphinx-test-reports#148
useblocks/sphinx-codelinks#95 — CommentType.markdown via tree-sitter	HartmannNico	2 commits, 13 files, +158/−5	conflicting	closes the transferred markdown issue
useblocks/sphinx-codelinks#96 — comment text as one-line codelink description	floroks	1 commit, 25 files, +967/−4	conflicting	known to hit the manifest tables the import stripped
useblocks/sphinx-codelinks#99 — marked-RST blocks in src-trace	cpolzer	3 commits, 8 files, +173/−3	conflicting	one of three marked-RST approaches
useblocks/sphinx-codelinks#100 — marker scope association in the declarative extraction	ubmarco	11 commits, 153 files, +2915/−1043	mergeable	tests only; measured before the import to move with zero conflicts

"Conflicting" means against the old repository's own main after its three pre-import pull requests landed, so each of those seven needs a rebase there before the recipe applies.

How a move works

The recipe rewrites the branch with the same git filter-repo rule the import used, so its commits apply on top of the import with their authorship intact. A moved pull request is opened here by whoever runs the recipe, credits the original author through the preserved commits, and the original is closed with a pointer. External contributors are not expected to run this themselves.

Decisions, deliberately deferred

1. Three marked-RST approaches (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) render RST from source comments in three different ways; at most one should move. Which one is a product decision.
2. needtable broken sorting and duplicate needs #93's -W/--strict overlaps with the same flag in sphinx-test-reports#148; one design for both is preferable to two.
3. For the rest: move, ask the author, or close as superseded — per PR, from the measured table below once it is in.

Measured move results

Measured on 2026-09-06/07 in scratch clones against master 758a43f2 and the old main 63adfe50, following the recipe verbatim for every PR: rebase onto the old main first, then git filter-repo with the import's rule (which put main on the exact commit the import merged, all eight times), then onto master, then the codelinks suite on the result (baseline 359 passed). Nothing was pushed.

old PR	old-main rebase	recipe onto master	suite on the result	recommendation	effort
#44 marked RST (juiwenchen)	9 conflict stops, 4 in real source, changelog hunks dropped	not reached	—	close; re-propose the idea as an issue	240+ min
#66 @rst blocks (chrisjsewell, draft)	2 mechanical + a snapshot-index collision	1 mechanical (isort re-sort)	378 passed	ask author: design open, superseded by #99	40 min
#82 TypeScript/JavaScript (arnoox)	5 stops, the fifth real: two incompatible refactors of test_analyse_oneline_needs	not reached	—	ask author	120+ min
#93 -W/--strict (ubmarco, draft)	4 mechanical	3 mechanical, incl. the analyse/utils.py git helper	396 passed	move with fixes	45 min
#95 markdown comment type (HartmannNico)	1 mechanical (changelog)	1 mechanical (changelog)	365 passed	move with fixes	20 min
#96 one-line description (floroks)	1 mechanical (manifest)	1 mechanical (the stripped tables)	387 passed	move with fixes	25 min
#99 marked RST in src-trace (cpolzer)	2 mechanical (import block)	2 mechanical (isort re-sort)	360 passed; zero new lint findings; docs -nW green	move with fixes	15 min
#100 marker scope, tests only (ubmarco)	clean	clean	383 passed	move as is	5 min

The three marked-RST approaches solve one issue (#1885, old #43) at three different layers. #99 hands each block to docutils inside the directive, so any RST renders, adds no configuration key, and is the smallest and the only non-draft one. #66 drives sphinx-needs' NeedDirective from a regex-parsed first directive, renders need directives only, and needs a sphinx-needs 6 floor bump its own description leaves undecided; its rst_mixed fixture is worth transplanting onto #99. #44 parses blocks with a Lark grammar in the analyse layer so the CLI's JSON carries structured needs, at the cost of a new runtime dependency and three configuration keys; it is really a different feature, aimed at non-Sphinx consumers, and is nine months stale with changes requested. #66 and #99 add a render method to the same file and would render every block twice if both landed. The measured recommendation: #99 survives; #66 folds in as a follow-up; #44 becomes an issue. The decision stays open here until it is taken.

Two things the recipe's own list does not name, learned on the way: the import re-sorted the imports in src_trace.py because sphinx_needs is first-party in the workspace, so any branch touching that import block conflicts at the recipe stage even after a clean rebase (it hit #66 and #99, one line each time); and git's rename detection carried the moved changelog for some branches and silently dropped the hunk for others, so every moved PR's changelog entry has to be checked by eye.

Also for whoever moves them: #99's title still says "(#43)" and should name #1885; #100's file list is capped at 100 by the API, the branch has 153.