Document the CTIM XTCE parsing benchmark as a regression guard

[medley56]

Summary

tests/benchmark/test_xtce_parsing_benchmarks.py exists to keep a specific, already-fixed performance bug from coming back, but nothing in the documentation said so. The benchmarking page presented CTIM's 37 ms as a neutral data point, no document stated the "under 100 ms" budget the test's own docstring refers to, and developers.md never mentioned that a benchmark suite exists at all.

This is a documentation-only change. Three edits:

1. docs/source/benchmarking.md — a new ### The CTIM Definition as a Regression Guard subsection appended to the existing ## XTCE Definition Parsing Performance section. It records CTIM's structure (1668 kB / 19,283 XML elements, 9,493 Parameter declarations across only 15 distinct parameter types, 39 SequenceContainers, 9,559 ParameterRefEntry references), explains why that shape makes it a good canary, tells the history, states the budget, and documents the --benchmark-autosave / --benchmark-compare workflow — which is the only way pytest-benchmark actually detects a regression.
2. docs/source/developers.md — a ### Benchmarks subsection under ## Testing, pointing contributors at tests/benchmark/ and the save/compare workflow before they change anything under space_packet_parser/xtce/ or packets.py, with a link to the benchmarking page.
3. CHANGELOG.md — a ### Changed entry under ## [Unreleased].

The existing CTIM table row is left alone; 37 ms is correct within noise.

The regression being documented

Early versions resolved a SequenceContainer's BaseContainer by searching the whole ContainerSet by name and then parsing the referenced container from scratch, entry list and all, with nothing memoizing the result. All 38 of CTIM's concrete containers declare the same abstract base, so that base was re-parsed 38 times, and the same pattern applied to ContainerRefEntry. Loading the definition took on the order of twelve seconds. Threading a container lookup table through SequenceContainer.from_xml dropped it by more than two orders of magnitude, and the benchmark was added in that same change. Notably, the bug was invisible to the correctness tests, which passed the whole time it was present — which is precisely why the benchmark is worth explaining rather than leaving as a bare number.

The budget is NOT enforced by CI — deliberately

Worth being explicit, because it is the main judgement call here. CI runs the benchmarks as part of the normal pytest invocation and then discards the timings entirely. Nothing is saved, compared, or gated. A reader could reasonably assume a benchmark running in CI is a gate; it is not.

Adding enforcement was considered and deliberately left out of scope. A bare assert benchmark.stats.stats.mean < 0.1 would be evaluated across the full CI matrix — Windows, macOS, five Python versions, shared runners — and is a likely source of intermittent red builds; a CI-side --benchmark-compare-fail needs durable, machine-matched baseline storage, which is a real design question and not one a documentation ticket should answer by hand. Rather than paper over the gap, a MyST {note} on the benchmarking page states it plainly and tells contributors touching space_packet_parser/xtce/ to run the comparison manually. Follow-up issue #287 tracks designing an actual gate.

Measured number

Re-measured on this branch before writing it down: 34.1 ms mean (min 33.0, max 38.8, 23 rounds), and 35.1 ms mean in a full-suite run. That is inside the page's existing hardware caveat — all numbers on that page are declared as measured in the project devcontainer on Apple Silicon — so no new caveat paragraph was added. The measured figure appears exactly once, in a sentence that hedges it; the load-bearing 100 ms number is stated as a policy decision rather than a measurement, so it does not rot when hardware changes.

Verification

• pre-commit run --all-files passes; prettier made no changes.
• make html builds clean with no new warnings.
• Confirmed in docs/build/html/benchmarking.html that the {note} renders as <div class="admonition note"> and not as literal text — 6.2.0 shipped a fix for exactly that rendering bug, so this uses the MyST fence, not > [!NOTE]. Both new tables render as tables.
• Confirmed ### Benchmarks appears in developers.html and its benchmarking.md link resolved to benchmarking.html.
• Every structural number in the prose was verified against ctim_xtce_v1.xml itself rather than taken on trust.
• Full suite: 481 passed.

Closes #147

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 88.88889% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 94.80%. Comparing base (71bc3d0) to head (bdc4e42).

Files with missing lines	Patch %	Lines
tests/benchmark/conftest.py	55.55%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #286      +/-   ##
==========================================
- Coverage   94.86%   94.80%   -0.07%     
==========================================
  Files          50       51       +1     
  Lines        4321     4347      +26     
==========================================
+ Hits         4099     4121      +22     
- Misses        222      226       +4     

☔ 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.

[Copilot]

🟢 Approval recommended

The documentation changes are reviewed; the only finding is a non-blocking nit about an issue reference.

Pull request overview

Documents the CTIM XTCE parsing benchmark as a manual performance regression guard.

Changes:

• Adds CTIM benchmark context, history, budget, and comparison workflow.
• Documents benchmark guidance for contributors.
• Records the update in the unreleased changelog.

File summaries

File	Summary
docs/source/developers.md	Adds benchmark guidance and workflow.
docs/source/benchmarking.md	Documents CTIM’s regression-guard purpose.
CHANGELOG.md	Records the documentation update.

Review details

Suppressed comments (1)

docs/source/benchmarking.md:293

• The PR description says follow-up issue #285 tracks designing this CI gate, but repository issue #285 is actually about invalid CITATION.cff metadata and is unrelated. Please correct the issue reference in the PR description (or omit it) so the rationale for leaving enforcement manual remains traceable.

budget is currently a manual step. If you are touching `space_packet_parser/xtce/`, run the
comparison above before opening a PR.

• Files reviewed: 3/3 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[medley56]

This is really what we should do. Documentation is not harmful, but the real solution to this is to check benchmarks against thresholds. If a set threshold is exceeded, that should fail the build. This changes the scope of this PR but that is OK. We should implement the real solution.

[medley56]

This is too verbose. We should rely on CI tests checking this regression state, not a document that likely no one will read. Again, this is changing the scope of the PR but it's clear that we should actually check this in CI.