[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 title with no hand-editing. allow_merge_commit is false today; the steps are under
Before merging below.

useblocks/sphinx-test-reports moves into this workspace as packages/sphinx-test-reports/,
with its history, its ten release tags and its release path. It is the fourth distribution here
— and the first whose runtime dependency on a sibling is optional, which is where most of the
interesting parts below come from.

What the import is

The whole of that repository's master — 161 commits, tip ca74b80 (🚀 Release v2.0.0) —
rewritten by git filter-repo so that every historical commit already places its files under
packages/sphinx-test-reports/. 227 files in the merge, and nothing outside the package.

• Tags. Its ten releases arrive prefixed, sphinx-test-reports-v0.3.6 …
  sphinx-test-reports-v2.0.0. The prefix is load-bearing: six of the ten bare names — 1.0.1,
  1.0.2, 1.1.0, 1.2.0, 1.3.0, 2.0.0 — are existing sphinx-needs releases, and
  release_plan.py reads every tag without -v in it as a sphinx-needs release.

• A scoped commit-message rewrite. Bare issue numbers became useblocks/sphinx-test-reports#N,
  150 of them, bounded to that repository's own number range, 1 to 161. Exactly three references
  are deliberately left bare: ⬆️ Drop Python 3.9 #1468, 👌 Add schema to add_extra_option #1527 and ✨ Add needs_fields, deprecate need_extra_options, need_statuses, need_tags #1611, all in one commit (build: require
  sphinx-needs 6.0.1 and Sphinx 7.4), are sphinx-needs issues — ⬆️ Drop Python 3.9, 👌 Add
  schema to add_extra_option, ✨ Add needs_fields. Left bare they autolink here to exactly the
  issues they mean; a lazy rule would have mangled all three into references that do not exist,
  which was measured by running it. The merge commit's own message was written by hand after
  filtering, so the rule never reached it: every sphinx-test-reports reference in it is written out
  in full for the same reason.

• The commit map, at packages/sphinx-test-reports/design/import-commit-map.txt. Ten released
  versions' GitHub Releases, changelog entries and PyPI page are full of the old hashes; the old
  repository is archived rather than deleted, and this file carries them across.

• One deliberate departure from a byte-for-byte copy — the PlantUML jars. The filter also
  stripped three jar blobs, 19.97 MB, from every historical tree. Unstripped the import adds
  +18.75 MiB of objects to a repository whose whole object set is ~101.6 MiB; stripped,
  +1.07 MiB. This workspace already vendors one PlantUML jar, at vendor/plantuml/, under a
  verify-plantuml gate.

  The imported tree differs from the source by exactly those jars, and that is checkable. Run it
  against the import commit, 918f3cd3, which is what the claim is about:

  git clone https://github.com/useblocks/sphinx-test-reports.git /tmp/str
  mkdir -p /tmp/a /tmp/b
  git -C /tmp/str archive ca74b80 | tar -x -C /tmp/a
  git archive 918f3cd3:packages/sphinx-test-reports | tar -x -C /tmp/b
  diff -rq /tmp/a /tmp/b
  # Only in /tmp/a/docs: utils                        <- contained plantuml.jar, nothing else
  # Only in /tmp/a/tests/doc_test/utils: plantuml.jar

  At HEAD the same command prints about sixty lines, because the ten commits after the merge change
  the package — that is the point of them, and each is described below. (A reviewer of this branch
  also compared all 161 imported trees against the source by mode and blob sha, not just the
  tip: zero mismatches.)

How to read the history afterwards

git log packages/sphinx-test-reports/<path> works with no --follow — filter-repo rewrote the
paths. git blame needs nothing, and git log --first-parent master shows the import as one line.

If you have an open pull request in the old repository

Once this pull request is merged, its commits move across with their authorship. Not before: until then master here has no packages/sphinx-test-reports/, and the cherry-pick below stops with modify/delete conflicts — measured, on useblocks/sphinx-test-reports#68. The property that makes it work is that
filter-repo's rewrite is deterministic: filtering your branch with exactly the rules below puts
its history on the very commit this import merged, so only your own commits need applying.

# clone pr-move NEXT TO your checkout of useblocks/sphinx-needs: the second half reaches it as ../pr-move
git clone https://github.com/useblocks/sphinx-test-reports.git pr-move && cd pr-move
git fetch origin '<your-branch>:pr-branch'
# for a fork: git fetch https://github.com/<you>/sphinx-test-reports.git '<your-branch>:pr-branch'
printf '%s\n' 'regex:(?<![\w/])#([1-9]|[1-9][0-9]|1[0-5][0-9]|16[01])\b==>useblocks/sphinx-test-reports#\1' > ../rules.txt
uvx git-filter-repo --to-subdirectory-filter packages/sphinx-test-reports \
    --tag-rename ':sphinx-test-reports-v' --replace-message ../rules.txt \
    --path-glob '*.jar' --invert-paths --force
# then, in your checkout of useblocks/sphinx-needs, beside pr-move:
git remote add prmove ../pr-move
git fetch prmove master pr-branch
git checkout -b <new-branch-name> origin/master   # a name not already used here, e.g. str-pr-68
git rev-list --reverse --no-merges "$(git merge-base prmove/master prmove/pr-branch)..prmove/pr-branch" \
    | git cherry-pick --stdin

Three details differ from the sphinx-codelinks import's recipe, and each was learned by running it:

• --path-glob '*.jar' --invert-paths is not optional. This import stripped the jars, so a
  filter without the strip produces a different history: measured, master comes out as
  206c6494 instead of ffdf962e, and nothing you cherry-pick lands on the imported commits.
• The old repository's default branch is master, and the branch is fetched as pr-branch,
  so that a fork whose branch is itself called master does not collide with the clone's own. For
  the same reason the branch you create here takes a new name: every sphinx-needs checkout already
  has a local master, and git checkout -b master there stops with fatal: a branch named 'master' already exists.
• --no-merges. A plain git cherry-pick <base>..<branch> stops at the first merge commit in
  your branch. Dropping merges is safe only when they resolved nothing: check with
  git show --cc <merge>, which prints a diff only for hunks resolved by hand. If any merge in your
  branch did resolve a conflict, rebase your branch onto master in the OLD repository first,
  which linearises it, and then move it.

Proven end to end on useblocks/sphinx-test-reports#68, the one open pull request from an
outside contributor — a fork branch named master, one commit plus one merge of the upstream
branch, and behind master. The merge was trivial (git show --cc is empty); the move applied
one commit with zero conflicts, following the file's rename into src/ on its own; the
original author is preserved on it (the committer becomes whoever runs the recipe); and the net
change of each of its three files is byte-identical to the pull request's. On the moved branch
ruff check, ty, its own seven tests, the whole package suite and the subprocess fence are all
green. The one thing it needs is a ruff format pass over tests/test_tr_link.py.

useblocks/sphinx-test-reports#68 is still mergeable in the old repository, but that repository's master has not moved from
ca74b80 since this import was cut, so merging it there now would leave it out of this import.
Moving it with the recipe is the route.

Then resolve anything this import changed under your branch, and push. The list, most likely
first:

• formatting and lint — the workspace's ruff format and ruff check now apply to this
  package (on Support pattern matching in tr_link sphinx-test-reports#68, one file needed formatting and nothing else);
• the member's pyproject.toml — [dependency-groups], [tool.ruff.lint],
  [tool.pytest.ini_options] and [tool.mypy] no longer exist there, and there is no test extra;
  a new test dependency goes in the ROOT test group;
• files this import retired — noxfile.py, Makefile, .github/, .pre-commit-config.yaml,
  .yamlfmt, CONTRIBUTING.md — which a branch that edits them hits as a modify/delete conflict;
• the directive modules the type-checking port rewrote, above all directives/test_common.py;
• a test that spawns sphinx-build must build its argv with
  sphinx_needs_testkit.sphinx_build_command, or the subprocess fence fails.

A file that moved under src/ is not on this list: the cherry-pick follows the rename.

Two further pull requests there come from maintainers and already conflict with master in the
old repository: useblocks/sphinx-test-reports#117 (mypy fixes, 29 commits, 21 files — much of what
it touches is retired or re-done here with ty) and useblocks/sphinx-test-reports#63 (the JUnit
error attribute). Whether to move or close them is left to their authors.

A warning for anyone grepping the diff

tests/doc_test/utils/*.xml contain the literal string sphinxcontrib/ — for example
file="sphinxcontrib/test_reports/junitparser.py". They are fixture payloads describing a
historical pytest run: test data, not paths anything opens. A src/-move sed would corrupt them
silently. They are untouched, and their 23 files are byte-identical to the import.

What changed beyond the move

One commit each.

1. Wiring and the relock — the one --no-verify commit, and it has to be: members = ["packages/*"] discovers the directory the moment the merge lands, so uv sync --frozen and three
   hooks fail together until the lock catches up. The manifest is truncated to what a member may own;
   requires-python becomes >=3.11,<4; both sphinx-needs specifiers become >=8.5.0,<9. The
   lock gains one name, one entry, zero third-party distributions and zero bytes to download. This
   commit also adds the commit map, and deletes 22 sys.path.insert(… "../../sphinxcontrib") lines
   from fixture conf.py files: the src/ move is what made that path false.
2. Retirements. The noxfile, Makefiles, standalone CI, pre-commit and yamlfmt configs,
   .gitignore, CONTRIBUTING.md. AUTHORS is kept. Two things retire with no replacement, and
   are named because nothing else in the diff says so: linkcheck (the workspace's docs.yaml is
   scoped to sphinx-needs' docs) and three prek hooks (end-of-file-fixer, trailing-whitespace,
   pretty-format-json).
3. ruff + ty. 56 ruff findings and 62 ty diagnostics, now zero, ported here rather than
   excluded, because an unchecked member is invisible. ~45 of the 62 had one cause: eleven directive
   attributes initialised to a bare None. Five narrow # ty: ignore remain, each with its
   reason. The regression tests below land here, beside the fixes they cover.
4. The subprocess fence. Three tests spawned sphinx-build resolved on PATH; they now go
   through sphinx_needs_testkit.sphinx_build_command, with the one-line fence sphinx-mounts carries.
   And a failure that would have been green in CI and red for every developer: an in-process
   pytest.main() collides with pytest-playwright in the default .venv, which no CI cell has.
   Fixed with -p no:playwright on the inner session.
5. Docs — clean under -nW --keep-going, from five warnings.
6. Read the Docs config, re-rooted at the repository.
7. CI — one pytest step and one Codecov upload in the Extensions cell (flag reports); a new
   toolchain-free job, the fence that keeps the converter and the pytest plugin importable with
   no documentation toolchain (it cannot be a matrix cell, because every workspace environment
   installs every member and sphinx-needs declares sphinx at runtime); and a new Docs reports
   job, since nothing else would hold the zero-warning build. That job's PlantUML step is counted by
   tools/tests/test_ci_plantuml_steps.py, whose site counts go 7 → 8 and 6 → 7 — the fence asks for
   exactly that decision to be made explicitly.
8. The release workflow. The compat cell installs a bare wheel whose Requires-Dist is lxml
   alone, so this member gets a compat-requirements.txt; and module=${DIST//-/_} derived a module
   that does not exist, so the step now reads [tool.flit.module] name. Exercised by hand:
   without the file the import walk fails 6 of 25 modules; with it, 25 of 25 and the suite passes
   against published dependencies.
9. The lists that name the packages: labeler, issue labeler, both issue forms, the root README
   (which was already missing sphinx-codelinks — it now lists four of four), and AGENTS.md.
10. The changelog.
11. Two loader tests made portable to Windows, after CI's first Windows run of this suite (see below).

Three bug fixes, one deprecation cleanup, and one thing that is NOT fixed

• 🐛 A test-env with :raw: and :env: but no :data: raised TypeError — one branch
  iterated outside the guard its sibling keeps it inside. No fixture had that shape.
• 🐛 A test-file written without :file: raised an unhandled TypeError. The guard meant to
  catch it was dead code, reached only after a slice of the missing value. It now raises
  TestReportFileNotSetError. No fixture had that shape either.
• 🐛 This repository's own docs build could not resolve the report template's literalinclude
  after the src/ move.
• 👌 nodes.Text(text, text) → nodes.Text(text). Not a bug: docutils ignores the second
  argument, deprecates it, and removes it only in Docutils 2.0.
• ⚠️ The shipped default report template's self-include is still broken for users, and this pull
  request does not fix it. literalinclude resolves against the including document — for a
  user, somewhere in their own docs — so no path written in the shipped file can be right for both
  them and this repository. Filed as 🐛 The shipped default test-report template literalincludes itself by a path only this repository can resolve #1932. Until it is fixed a project can copy the template and remove the
  literalinclude directive at its end — both lines, or the whole Template section; removing
  only the first leaves a stray language: rst field list.

Each of the three code changes above — the two crashes and the Text() cleanup — comes with a
mutation-proved regression test, in a new tests/test_directive_regressions.py with three new
fixture projects: red on the published code, green on the fix. The fourth item, the docs build's own
template path, is not a pytest; the Docs reports job holds it, and it fails on the unfixed path.
The Text() test needed a warning filter scoped to docutils' exact deprecation message and to
this package's module — without it an assertion on the rendered error node passes on the old call
too, which was measured — and a positive control on the same pattern constant, so that a docutils
rewording fails loudly instead of disarming the fence.

Two pre-existing gaps fixed on the way past

• The Lint job's type-gate canary probed only two of the packages. sphinx-codelinks was already
  missing, so the hole was one package wide before this import. Both are now probed.
• The root README table was missing sphinx-codelinks.

What this costs, stated rather than left to the CI diff

• The sphinx-needs axis goes from five tested versions to one, and the declared floor narrows
  with it, from sphinx-needs>=6.0.1 to >=8.5.0,<9. Accepted.
• Five ruff families (FURB, PERF, PGH, PIE, SLF) are no longer enforced, and four more
  rules this package enabled are ignored by the shared set (B904, ICN001, ISC004, N818). All
  nine are at zero violations today.
• linkcheck and three formatting hooks retire with no replacement.
• plugin_floor has no replacement yet.
• The docs keep sphinx_immaterial; converging on furo has its own issue.

One effect on a sibling suite, which pass counts alone would hide

Putting sphinx-design in the shared test group moves one sphinx-needs test from skipped to
passing: test_needreport.py::test_sphinx_design_dropdown_output_is_unchanged, guarded by
skipif(not SPHINX_DESIGN_INSTALLED). The direction is good; it is stated because a pass count
cannot show a skip becoming a pass.

	before this branch	this branch
poe test-needs	1804 passed, 12 skipped	1805 passed, 11 skipped
poe test-mounts	944 passed, 2 deselected	944 passed, 2 deselected

Windows

Everything was measured locally on macOS and three Linux-shaped cells, so the Extensions
windows-latest × sphinx-9 cell was this suite's first run on Windows. The old repository's CI ran on
ubuntu-latest only. That first run failed two tests in tests/test_project_config.py::TestLoader,
both added with useblocks/sphinx-test-reports#145, and both test defects rather than product bugs:

• test_unreadable_file_is_a_config_error makes its file unreadable with chmod(0o000). On Windows
  os.chmod only sets the read-only attribute, so the file stays readable and nothing raised. It now
  skips on Windows, as it already did for root on POSIX.
• test_absolute_paths_stay_untouched wrote tmp_path into a TOML basic string, where a Windows path's
  backslashes are escape sequences, so the file was invalid TOML — which the loader correctly reported.
  It now uses a TOML literal string and checks the same thing on every platform.

Fixed in d68d10df. On it the Windows cell's sphinx-test-reports step reports:

run	passed	skipped	failed
f4075034	423	1	2
d68d10df	424	2	0

The three converted subprocess sites, the part expected to be Windows-sensitive, passed on the first run.

Gates

Every figure below was measured locally on f4075034. The one commit after it, d68d10df, changes two
tests for Windows and nothing else (see Windows above), and CI runs the full matrix on it.

poe lint              8/8 hooks             poe test-reports        426 passed
poe typecheck         All checks passed     cells sphinx-7 / 8 / 9  426 passed each
poe docs-reports      0 warnings            pytest tools/tests      313 passed
pytest --collect-only 2175, exit 0          check-workspace         all green
import_check --walk   25 modules            compat cell (by hand)   sphinx-needs 8.5.0 from PyPI,
                                                                    25 modules, 426 passed
mutation proofs       each proof red when its fix is reverted, green restored; the positive
                      control red when its pattern is broken

check_workspace.py check (5) prints no line for this member, by design and for two
independent reasons (a dotted module name, and no __version__ literal); the package's AGENTS.md
says so, and the release that renames the module dissolves both.

Follow-up candidates, not in this pull request

• the shipped template's self-include — 🐛 The shipped default test-report template literalincludes itself by a path only this repository can resolve #1932;
• converging the docs theme on furo;
• widening docs.yaml's linkcheck to this package;
• schema={"type": …} against sphinx-needs' TypedDict union — a real API-shape mismatch, suppressed
  here with a reason;
• plugin_floor;
• three things no gate currently fences: a typo in the labeler glob (which is what applies
  pkg: sphinx-test-reports to every future pull request), the [project.urls] values, and the
  toolchain marker line — removing any of them leaves every gate green.

Before merging

• Create the label pkg: sphinx-test-reports, and apply it to this pull request by hand. The
  pull_request_target labeler reads the default branch's configuration, which does not know this
  package until this merges, so it cannot apply the label here however early the label exists. It
  must exist before the merge and before any issue is transferred.
• File the follow-up issue for the shipped template's self-include, carrying that label — 🐛 The shipped default test-report template literalincludes itself by a path only this repository can resolve #1932.
• Flip allow_merge_commit on immediately before the merge, merge with Create a merge
  commit, and flip it off immediately after.

After the merge

• Push the ten sphinx-test-reports-v* tags, before creating any Read the Docs automation
  rule (rules run on version creation).
• Read the Docs: repoint the project's repository URL at useblocks/sphinx-needs and set
  readthedocs_yaml_path to packages/sphinx-test-reports/.readthedocs.yaml. Needs danwos or
  ub_marco.
• Transfer the open issues, each with the new label; close 🔧 Prepare sphinx-test-reports for its move into the sphinx-needs workspace sphinx-test-reports#149 with
  a pointer here; point the Support pattern matching in tr_link sphinx-test-reports#68 contributor at the recipe above; pin a "this repository has moved" issue; archive rather than delete the old repository.
• Delete the superseded import/sphinx-test-reports branch.

Closes nothing — useblocks/sphinx-test-reports#149 is closed by hand in the other repository.

[codecov]

Codecov Report

❌ Patch coverage is 88.75267% with 211 lines in your changes missing coverage. Please review.
✅ Project coverage is 91.69%. Comparing base (eb23d5e) to head (d68d10d).
⚠️ Report is 23 commits behind head on master.

Files with missing lines	Patch %	Lines
...ts/src/sphinxcontrib/test_reports/pytest_plugin.py	59.78%	76 Missing ⚠️
.../sphinxcontrib/test_reports/directives/test_env.py	82.00%	27 Missing ⚠️
...phinxcontrib/test_reports/directives/test_suite.py	75.00%	24 Missing ⚠️
...sphinxcontrib/test_reports/directives/test_case.py	85.29%	15 Missing ⚠️
...orts/src/sphinxcontrib/test_reports/environment.py	75.00%	12 Missing ⚠️
...rts/src/sphinxcontrib/test_reports/test_reports.py	93.67%	10 Missing ⚠️
...reports/src/sphinxcontrib/test_reports/__init__.py	63.63%	8 Missing ⚠️
...hinxcontrib/test_reports/directives/test_common.py	92.59%	8 Missing ⚠️
...ts/src/sphinxcontrib/test_reports/projectconfig.py	96.70%	8 Missing ⚠️
...test-reports/src/sphinxcontrib/test_reports/cli.py	96.11%	7 Missing ⚠️
... and 6 more

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1931      +/-   ##
==========================================
- Coverage   91.84%   91.69%   -0.15%     
==========================================
  Files         105      129      +24     
  Lines       16231    18155    +1924     
==========================================
+ Hits        14907    16648    +1741     
- Misses       1324     1507     +183     

Flag	Coverage Δ
codelinks	93.42% <ø> (ø)
mounts	94.01% <ø> (ø)
pytests	91.40% <ø> (+0.27%)	⬆️
reports	88.75% <88.75%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[ubmarco]

LGTM